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Introduction 


In 1975, Microsoft wrote the first BASIC interpreter for microcomputers. 
Today, Microsoft BASIC has well over 1,000,000 installations and is used 
in Many operating environments. It’s the BASIC you will find on all of the 
most popular microcomputers. Many users, manufacturers, and software 
vendors have written application programs in Microsoft® BASIC. 


The BASIC interpreter is a general-purpose programming language: it is 
effective for many applications, including business, science, games, and 
education. It is interactive; that is, without writing a program, a user can 
perform processes, calculations, and program testing. 


Microsoft GW™-BASIC 2.0 is the most extensive implementation of 
Microsoft BASIC available for microprocessors. It meets the require- 
ments for the ANSI subset standard for BASIC, and supports many 
features rarely found in other BASIC interpreters. In addition, the Micro- 
soft GW-BASIC 2.0 Interpreter has sophisticated screen handling, graph- 
ics, and structured programming features that are especially suited for 
application development. 


1-] 


Introduction 


1.1 OVERVIEW 


GW-BASIC 2.0 includes several features not found in other BASICs, and 
has been designed to take advantage of the MS™-DOS 2.0 environment to 
enhance programming power. 


Some of the new features and improvements over GW-BASIC 1.0 are: 


Re-direction of Standard Input (INPUT, LINE INPUT) and 
Standard Output (PRINT) 


Character Device support which allows BASIC to initialize and 
communicate with user-installed devices 


Improved Disk I/O facilities for handling larger files 


SHELL which allows COMMAND or Child processes to run 
without having to leave BASIC 


Multi-level directories for better disk organization 
Directory management (MK DIR/CHDIR/RMDIR) 
Improved Graphics: Line Clipping, VIEW, WINDOW 
Screen Editor enhancements including text window support 
Additional Event Trapping: PLAY, TIMER 

User definable Keyboard trapping 


More precise error reporting with the new system functions: 
ERDEV and ERDEV$ 


Double Precision Transcendentals (optional with the /D switch) 


More precise control of BASIC’s memory allocation for user 
routines with the /M: switch 


12 SYNTAX NOTATION 


When commands are discussed in this document, the following notation 
will be followed: 


[ ] Square brackets indicate that the enclosed entry is 
optional. 
< - Angle brackets indicate user-entered data. When the 


angle brackets enclose lowercase text, the user must type 
in an entry defined by the text; for example, <filename>. 
When the angle brackets enclose uppercase text, the user 
must press the key named by the text; for example, 
<RETURN>. 
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Braces indicate that the user has a choice between two or 
more entries. At least one of the entries enclosed in braces 
must be chosen unless the entries are also enclosed in 
square brackets. 


Vertical bars separate choices within braces. At least one 
of the entries separated by bars must be chosen unless the 
entries are also enclosed in square brackets. 


Ellipses indicate that an entry may be repeated as many 
times as needed or desired. 


Capital letters indicate portions of statements or com- 
mands that must be entered exactly as shown. 


All other punctuation, such as commas, colons, slash marks, and equal 
signs, must be entered exactly as shown. 


Examples 


Command Line Explanation 


SAVE <filespec> [{A|P}] 
aN 


pee 


aN 


L—-_——_- These two entries are optional as 
indicated by the square brackets. They 
also must be typed in as shown. The 
braces indicate an either/or choice. 


aims ere aieaeles an The lowercase filespec means you 


must supply the file specification (disk 
drive, filename and extension). 


eR SLUT a ee nae a ee ae Capital letters indicate that the word 


must be entered exactly as shown. 
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1.3 > RESOURCES FOR LEARNING BASIC 


This manual provides complete instructions for using Microsoft BASIC. 
However, no training material for BASIC programming has been pro- 
vided. If you are new to BASIC or need help in learning programming, we 
suggest you read one of the following: 


Dwyer, Thomas A. and Critchfield, Margot. BASIC and the Personal 
Computer. Reading, Mass.: Addison-Wesley Publishing Co., 1978. 


Albrecht, Robert L., Finkel, LeRoy, and Brown, Jerry. BASIC. New 
York: Wiley Interscience, 2nd ed., 1978. 


Billings, Karen and Moursund, David. Are You Computer Literate? 
Beaverton, Oregon: Dilithium Press, 1979. 


Coan, James. Basic BASIC. Rochelle Park, N.J.: Hayden Book Com- 
pany, 1978. 
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Using the GW-Basic aa 
2.0 Interpreter 





2.1 INVOKING BASIC 


To begin operating the GW-BASIC Interpreter, load the MS-DOS oper- 
ating system and then enter: 


BASIC 


To begin operating a specific program as soon as BASIC has started, load 
the operating system and enter: 


BASIC <filespec> 


where <filespec> is a filename preceded by an optional device designator, 
and followed by an optional extension name. 


For example, to start the program FILE.BAS which is on disk drive A:, 
enter: 


BASIC A:FILE.BAS 
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2.2 COMMAND LINE OPTION SWITCHES 


The BASIC operating environment may be altered somewhat by specify- 
ing option switches following BASIC on the command line. The format of 
BASIC’s command line is: 


BASIC _ [<stdin] 
[>stdout] 
[<filespec>] 
[/C:<buffer size>] 
[/D] 
[ / F:<number of files>] 
[/1] 
[/M:[<highest memory location>] 
[,<maximum block size>]] 
[/S:<lrecl>] 


WHERE: 


<stdin 


BASIC input is redirected from the file specified by stdin. When 
present, this syntax must appear before any switches. Note that the 
less-than character “<”’ 1s literally that character, and not an angle 
bracket indicating a required argument. 


>stdout 


BASIC output is redirected to the file specified by stdout. When 
present, this syntax must appear before any switches. If two 
greater-than signs appear (“>>”), the output is appended to an 
existing output file. If an existing file is to be written to, this is the 
way to prevent that file from being overwritten. Note that the 
greater-than character “>” is literally that character, and not an 
angle bracket indicating a required argument. 


<filespec> 


This is the file specification of a BASIC program. If <filespec> is 
present, BASIC proceeds as if a RUN <filespec> command were 
given after initialization is complete. This allows BASIC programs 
to be initiated by a batch file by putting this form of the command 
line in an AUTOEXEC.BAT file. Programs run in this manner 
will need to exit via the SYSTEM statement in order to allow the 
next command from the AUTOEXEC.BAT file to be executed. 
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/F:<number of files> 


This switch is ignored unless the /I switch is specified on the 
command line. Please refer to the /I switch documentation below. 


If this switch and the /I switch are present, the maximum number 
of files that may be open simultaneously during the execution of a 
BASIC program is set to <number of files>. Each file requires 62 
bytes for the File Control Block (FCB) plus 128 bytes for the data 
buffer. The data buffer size may be altered via the /S: option 
switch. If the /F: option is omitted, the number of files is set to 3. 


The number of open files that MS-DOS supports depends upon 
the value of the FILES= parameter in the CONFIG.SYS file. It is 
recommended that FILES=10 for BASIC. Keep in mind that the 
first 3 are taken by Stdin, Stdout, Stderr, Stdaux, and Stdprn. One 
additional handle is needed by BASIC for LOAD, SAVE, 
CHAIN, NAME, and MERGE. This leaves 6 for BASIC File I/O, 
thus / F:6 is the maximum supported by MS-DOS when FILES=10 
appears in the CONFIG.SYS file. 


Attempting to OPEN a file after all the file handles have been 
exhausted will result in a “Too many files” error. 


/S:<lrecl> 


This switch is ignored unless the /I switch is specified on the 
command line. Please refer to the /I switch documentation below. 


If this switch and the /I switch are present, then the maximum 
record size allowed for use with random files is set to <lIrecl>. 
NOTE: the record size option to the OPEN statement cannot 
exceed this value. If the /S: option is omitted, the record size 
defaults to 128 bytes. 


/C:<buffer size> 


If present, this switch controls RS232 Communications. If RS232 
cards are present, /C:0 disables RS232 support. Any subsequent 
I/O attempts will result in a “Device Unavailable” error. Specify- 
ing /C:<n> allocates space for communications buffers. The 
amount of space allocated is dependent on the machine-specific 
portion of GW-BASIC. 
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/D 


If present, this switch causes the Double Precision Transcendental 
math package to remain resident. If omitted, this package 1s dis- 
carded and the space is freed for program use. 


/I 

GW-BASIC is able to dynamically allocate space required to 
support file operations. For this reason, GW-GASIC does not 
need to support the /S and / F switches. However, certain applica- 
tions have been written in such a manner that certain BASIC 
internal data structures must be static. In order to provide compat- 
ibility with these BASIC programs, GW-BASIC will statically 
allocate space required for file operations based on the /S and /F 
switches when the /I switch is specified. 


/M:[<highest memory location>] [,<max block size>] 


When present, this switch sets the highest memory location that 
will be used by BASIC. BASIC will attempt to allocate 64K of 
memory for the data and stack segment. If machine language 
subroutines are to be used with BASIC programs, use the /M: 
switch to set the highest location that BASIC can use. When 
omitted or 0, BASIC attempts to allocate all it can up to a maxi- 
mum of 65536 bytes. 


If you intend to load things above the highest location that BASIC 
can use, then use the optional parameter <maximum block size> 
to preserve space for them. This is necessary if you intend to use the 
SHELL statement (see Section 7.148). Failure to do so will result 
in COMMAND being loaded on top of your routines when a 
SHELL statement is executed. 


<maximum block size> must be in paragraphs (byte multiples of 
16). When omitted, &H1000 (4096) is assumed. This allocates 
65536 bytes (65536= 4096 x 16) for BASIC’s data and stack seg- 
ment. For example, if you wanted 65536 bytes for BASIC and 256 
bytes for machine language subroutines, then use /M:,&H1010 
(4096 paragraphs for BASIC + 16 paragraphs for your routines). 
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This option can also be used to shrink the BASIC block in order to 
free more memory for shelling other programs. / M:,2048 allocates 
32768 bytes for data and stack. /M:32000,2048 allocates 32768 
bytes maximum, but BASIC will only use the lower 32000. This 
leaves 768 bytes for the user. 


NOTE 


<number of files>, <lIrecl>, <buffer 
size>, <highest memory location>, and 
<maximum block size> are numbers that 
may be decimal, octal (preceded by &O), 
or hexadecimal (preceded by &H). 


Example: 


A>BASIC PAYROLL Use 64K of memory and 3 files, 
load and execute PAYROLL.BAS. 


A>BASIC INVENT/I/F:6 Use 64K of memory and 6 files, 
load and execute INVENT.BAS. 


A>BASIC /C:0/M:32768 Disable RS232 support and use 
only the first 32K of memory. The 
memory above that is free for the 
user. | 


A>BASIC /1/F:4/S:512 Use 4 files and allow a maximum 
: record length of 512 bytes. 


A>BASIC TTY/C:512 Use 64K of memory and 3 files. 
Allocate 512 bytes to RS232 re- 
ceive buffers and 128 bytes to 
transmit buffers, load and execute 
TTY.BAS. 


2-5 


Using the GW-BASIC 2.0 INTERPRETER 


2.3 MODES OF OPERATION 


The Microsoft GW-BASIC Interpreter may be used in either of two 
modes: direct mode or indirect mode. 


In direct mode, statements and commands are executed as they are 
entered. They are not preceded by line numbers. After each direct state- 
ment followed by a carriage return, the screen will display the “Ok” 
prompt. Results of arithmetic and logical operations may be displayed 
immediately and stored for later use, but the instructions themselves are 
lost after execution. Direct mode is useful for debugging and for using the 
GW-BASIC Interpreter as a calculator for quick computations that do not 
require a complete program. 


Indirect mode is used for entering programs. Program lines are preceded 
by line numbers and may later be stored in memory. The program stored in 
memory is executed by entering the RUN command. 


2.4 LINE FORMAT 


Microsoft GW-BASIC program lines have the following format (square 
brackets indicate optional input): 


<nnnnn><BASIC statement>[:BASIC statement...] <carriage 
return> 


More than one GW-BASIC statement may be placed on a line, but each 
must be separated from the last by a colon. 


A Microsoft GW-BASIC program line always begins with a line number 
and ends with a carriage return. Line numbers indicate the order in which 
the program lines are stored in memory. Line numbers are also used as 
references in branching and editing. Line numbers must be in the range 0 
to 65529. 


A line may contain a maximum of 255 characters. 
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With the interpreter, you can extend a logical line over more than one 
physical line by entering a <linefeed>. <linefeed> lets you continue 
typing a logical line on the next physical line without entering a <carriage 
return>. Alternatively, you may type up to 255 characters on a logical line 
without issuing either a line feed or a carriage return; the text is wrapped 
and continues on the next physical line. 


A period (.) may be used in EDIT, LIST, AUTO, and DELETE com- 
mands to refer to the current line. 


2.5 ACTIVE AND VISUAL (DISPLAY) PAGES 


The size of these pages is set by the SCREEN statement. (See SCREEN 
Statement, Section 7.138.) 
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Learning the Language oF 


Like any language, BASIC has an alphabet and common phrases. This 
chapter presents the BASIC character set, and the rules for the constants, 
variables, and expressions that the programming language uses. 


3.1 CHARACTER SET 


The Microsoft GW-BASIC character set consists of alphabetic characters, 
numeric characters, and special characters. 


The alphabetic characters in GW-BASIC are the uppercase and lowercase 
letters of the English alphabet. 


The GW-BASIC numeric characters are the digits 0 through 9. The 


alphabetic characters A, B, C, D, E, and F may be used as part of 
hexadecimal numbers. 
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3.1.1 Special Characters 


The following special characters and terminal keys are recognized by 
GW-BASIC: 


CHARACTER ACTION 
Blank 
= Equals sign or assignment symbol 
+ Plus sign 
- Minus sign 
‘a Asterisk or multiplication symbol 
/ Slash or division symbol 
i Up arrow or exponentiation symbol 
( Left parenthesis 
) Right parenthesis 
% Percent 
# Number (or pound) sign 
$ Dollar sign 
! Exclamation point 
[ Left bracket 
| Right bracket 
; Comma 


Period or decimal point 

Single quotation mark (apostrophe) 
: Semicolon 

Colon 

Ampersand 

Question mark 

Less than 

Greater than 

Backslash or integer division symbol 


@’°VA +R» 


At sign 
— Underscore 


_ 
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<escape> Escapes edit mode subcommands. 
<tab> Moves print position to next tab stop. Tab stops 
are set every eight columns. 
<return> Terminates input of a line. 


3.1.2 Control Characters 
Microsoft GW-BASIC supports the following control characters: 


CONTROL 
CHARACTER ACTION 

Control-B Moves cursor to previous word. 

Control-C Withthe interpreter, interrupts program execution 
and returns to BASIC command level. 

Control-E —_ Clears to end of line. 

Control-F | Moves cursor to the next word. 

Control-G Sounds the speaker. 

Control-H — Backspaces. Deletes the last character typed. 

Control-I Tabs to the next tab stop. Tab stops are set every 
eight columns. 

Control-K Sends cursor to home location. 

Control-L —_ Clears the screen. 

Control-N Moves cursor to the end of the line. 

Control-R Toggles the insert and typeover modes. 

Control-S Suspends program execution. 

Control-T — Updates the function key display line. 

Control-U Deletes the line that is currently being typed. 

Control-W _ Deletes the word that is at the cursor. 
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Control-X Displays the previous program line if the line at the 
cursor starts with a number. 


Control-Y Displays the next program line if the line at the 
cursor starts with a number. 


Control-Z Clears from the cursor to the end of the screen. 


3.2 CONSTANTS 


Constants are the values that cannot be changed during execution. There 
are two types of constants: string and numeric. 


3.2.1 String and Numeric Constants 


A string constant is a sequence of up to 255 alphanumeric and specified 
control characters enclosed in double quotation marks. 


Examples: 


“HELLO” 
“$25,000.00” 


“Number. of Employees” 


Numeric constants are. positive or negative numbers. Microsoft GW- 
BASIC numeric constants cannot contain commas. There are five types of 


numeric constants: 

1. Integer constants 

2. Fixed-point 
constants 


3. Floating-point 
constants 


Whole numbers between —32768 and 32767. Integer 
constants do not contain decimal points. 


Positive or negative real numbers, 1.e., numbers 
that contain decimal points. 


Positive or negative numbers represented in expo- 
nential form (similar to scientific notation). A 
floating-point constant consists of an optionally 
signed integer or fixed-point number (the man- 
tissa) followed by the letter E and an optionally 
signed integer (the exponent). The allowable range 
for floating-point constants is 10-38 to 10+38. 


VS 
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Examples: 


235.988E-7 = .0000235988 
2359E6 = 2359000000 


(Double precision floating-point constants are 
denoted by the letter D instead of E.) 


4. Hex constants Hexadecimal numbers, denoted by the prefix &H. 
Hex constants may be no greater than decimal 
64K. 

Examples 
&H76 
&H32F 

5. Octal constants Octal numbers, denoted by the prefix &0 or &. 
Octal constants may not exceed decimal 64K 
Examples: 

&0347 
& 1234 

3.2.2 Single/Double Precision Numeric Constants 

Numeric constants may be either single precision or double precision 

numbers. Single precision numeric constants are stored with 7 digits of 

precision and printed with up to 6 digits of precision. Double precision 


numeric constants are stored with 16 digits of precision and printed with 
up to 16 digits. 


A single precision constant is any numeric constant that has one of the 
following characteristics: 


1. Seven or fewer digits 
2. Exponential form using E 


3. A trailing exclamation point (!) 
Examples: 


46.8 
—1.09E-06 
3489.0 

a 


A double precision constant is any numeric constant that has one of these 
characteristics: 
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1. Eight or more digits 
2. Exponential form using D 
3. A trailing number sign (#) 


Examples: 


3456928 1 1 
-1.09432D-06 
3489.0# 
7654321.1234 


3.3 VARIABLES 


Variables are names used to represent values used in a GW-BASIC pro- 
gram. The value of a variable may be assigned explicitly by the pro- 
grammer, or it may be assigned as the result of calculations in the program. 
Before a variable is assigned a value, its value is assumed to be zero (or null 
for a string variable). 


3.3.1 Variable Names and Declaration Characters 


Microsoft GW-BASIC variable names may be any length. Up to 40 
characters are significant. Variable names can contain letters, numbers, 
and the decimal point. However, the first character must be a letter. 
Special type declaration characters (listed below) are also allowed. 


A variable name may not be a reserved word, but embedded reserved 
words are allowed, with one exception: no variable may start with the 
letters USR. For example, the variable USRNAMS$ will generate a syntax 
error. Reserved words include all Microsoft GW-BASIC commands, 
statements, function names, and operator names. If a variable begins with 
FN, it is assumed to be a call to a user-defined function. 


Variables may represent either a numeric value or a string. String variable 
names are written with a dollar sign ($) as the last character. For example: 
A$ = “SALES REPORT”. The dollar sign is a variable type declaration 
character; that is, it “declares” that the variable will represent a string. 


Numeric variable names may be declared as integer, single precision, or 


double precision values. The type declaration characters for these variable 
names are as follows: 
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% Integer variable 
! Single precision variable 
# Double precision variable 


The default type for a variable name is single precision. However, if a 
number specified in a program has too many significant digits to be 
represented by a single precision number, it will be represented as a double 
precision number, and the“ ” which signifies double precision will follow 
the number in the program listing. 

Integer variables produce the fastest and most compact object code. For 
example, the following program executes approximately 30 times faster 
when the loop control variable “I” is replaced with “I%”, or when I is 
declared an integer variable with DEFINT. 


100 FOR I=1 TO 10 
120 A(I)=0 
140 NEXT I 


Examples of Microsoft GW-BASIC variable names: 


Pl# Declares a double precision value. 
MINIMUM! Declares a single precision value. 
LIMIT% Declares an integer value. 

N$ Declares a string value. 

ABC Represents a single precision value. 


The default variable type may be selectively changed by using the GW- 
BASIC statements DEFINT, DEFSTR, DEFDBL, and DEFSNG. These 
statements are described in detail in Section 7.33. 


3.3.2 Array Variables 


An array is a group or table of values referenced by the same variable 
name. Each element in an array is referenced by an array variable that is 
subscripted with an integer or an integer expression. An array variable has 
nameas many subscripts as there are dimensions in the array. For example 
V(10) would reference a value in a one-dimension array, T(1,4) would 
reference a value in a two-dimension array, and so on. The maximum 
number of dimensions for an array is 255. The maximum number of 
elements per dimension is 32,767. The maximum amount of space that 
may be taken for an array is 64K. 
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3.3.3 Space Requirements 


The following list gives only the number of bytes occupied by the values 
represented by the variable names. Additional requirements may vary 
according to implementation. 


Variables Type Bytes 


Integer 2 
Single precision 4 
Double precision 8 

3 


String 
Arrays Type Bytes... — —— Sas 
Integer 2 per element 


Single precision 4 per element 
Double precision 8 per element 
String 3 per element 
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3.4 EXPRESSIONS AND OPERATORS 


An expression may be a string or numeric constant, a variable, or a 
combination of constants and variables with operators. An expression 
always produces a single value. 


Operators perform mathematical or logical operations on values. GW- 
BASIC operators may be divided into three categories: 


1. Arithmetic 
2. Relational 


3. Logical 
Each category is described in the following sections. 


3.4.1 Precedence of Operations 


The GW-BASIC operators have an order of precedence; that is, when 
several operations take place within the same program statement, certain 
kinds of operations will be performed before others. If the operations are 
of the same level of precedence, the first to be executed will be the leftmost, 
and the last, the rightmost. The following is the order in which operations 
are executed. 


. Exponentiation 

. Negation 

. Multiplication & Division 
. Integer Division 

. Modulus Arithmetic 

. Addition & Subtraction 
. Relational Operators 
NOT 

AND 

. OR & XOR 

. EQV 

. IMP 


0MONADAUWHA AWN | 


em cE 
No — © 
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3.4.2 Arithmetic Operators 


The arithmetic operators, in order of evaluation, are: 


OPERATOR OPERATION SAMPLE EXPRESSION 
e Exponentiation XY : 
- Negation —~X 
ate Multiplication, Floating- X*Y 
point Division X/Y 
\ Integer division 12\6 =2 
MOD Modulus arithmetic 10 MOD 4=2 


(10/4=2 with remainder 2) 


‘= Addition, Subtraction X+Y 


You can change the order of evaluation by using parentheses. Operations 
within parentheses are performed first. Inside parentheses, the usual order 
of operations is maintained. 
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The following list gives some sample algebraic expressions and their 
Microsoft GW-BASIC counterparts. 


ALGEBRAIC EXPRESSION 


X+2Y 


Y 


xXx— ima 


X(-Y) 


BASIC EXPRESSION 


X+Y*2 


X-Y/Z 


X*Y/Z 


(X+Y)/Z 


(XA2AY 


(X “(Y “ Z) 


X*(-Y) 
Two consecutive operators 
must be separated by 
parentheses. 


3.4.2.1 INTEGER DIVISION AND MODULUS ARITHMETIC 


In addition to the six standard operators (addition, subtraction, multipli- 
cation, division, negation, and exponentiation), GW-BASIC supports 
integer division and modulus arithmetic. 
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Integer division is denoted by the backslash (\). The operands are rounded 
to integers (must be in the range -32768 to 32767) before the division is 
performed, and the quotient is truncated to an integer. 


Examples: 


100 LET DIVI1 = 10\4 
200 LET DIV2 = 25.68\6.99 
300 PRINT DIVI, DIV2 


will yield 
2 3 


Modulus arithmetic is denoted by the operator MOD. Modulus arith- 
metic yields the integer value that is the remainder of an integer division. 


Examples: 
10 PRINT 10.4 MOD 4, 25.68 MOD 6.99 
will yield 
2 5 
because (10/4=2 with a remainder 2) and (26/7=3 with a remainder 5). 


3.4.2.2 OVERFLOW AND DIVISION BY ZERO 


If division by zero is encountered during the evaluation of an expression, a 
“Division by zero” error message is displayed. Machine infinity (the 
largest number that can be represented in floating-point format) with the 
sign of the numerator is supplied as the result of the division, and execu- 
tion continues. If the evaluation of an exponentiation operator results in 
zero being raised to a negative power, the “Division by zero” error message 
is displayed, positive machine infinity is supplied as the result of the 
exponentiation, and execution continues. 


If overflow occurs, the interpreter displays an “Overflow” error message, 
supplies machine infinity with the algebraically correct sign as the result, 
and continues execution. 
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3.4.3 Relational Operators 


Relational operators are used to compare two values. The result of the 
comparison is either “true” (-1) or “false” (0). This result may then be used 
to make a decision regarding program flow. (See IF Statement, Section 
7.59.) 


The relational operators are: 


OPERATOR RELATION TESTED EXAMPLE 


Equality 


Inequality 
Less than 
Greater than 


Less than or equal to 





Greater than or equal to 


(The equal sign is also used to assign a value to a variable. See the LET 
statement, Section 7.78.) 


When arithmetic and relational operators are combined in one expression, 
the arithmetic is always performed first. For example, the expression 


X+Y<(T-1)/Z 
is true if the value of X plus Y is less than the value of T-1 divided by Z. 
More examples: 


IF SIN(X)<0 GOTO 1000 
IF I MOD J< >0 THEN K=K+1 
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3.4.4 Logical Operators 


The logical operator performs bit-by-bit calculation and returns a result 
which is either “true” (not zero) or “false” (zero). In an expression, logical 
operations are performed after arithmetic and relational operations. The 
outcome of a logical operation is determined as shown in Table 3-1. The 
operators are listed in order of precedence. 


Table 3-1 GW-BASIC Relational Operators Truth Table 


OPERATION RESULT 


NOT X 
Pp 
T 


X AND Y 
T 


VALUE VALUE 








X OR Y 
T 


5 Rae Be 


ores Jove fo ; 
PT} °° 


XxX Y xX XOR Y 
T T rE 
T F T 
F T T 
F F F 
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X EQV Y 
T 


X IMP Y 
T 





Just as the relational operators can be used to make decisions regarding 
program flow, logical operators can connect two or more relations and 
return a true or false value to be used in a decision (see IF Statements, 
Section 7.57). 


Example: 


IF D<200 AND F<4 THEN 80 
IF I>10 OR K<0 THEN 50 


IF NOT P THEN 100 


Logical operators work by converting their operands to 16-bit, signed, 
two’s complement integers in the range -32768 to 32767. (If the operands 
are not in this range, an error results.) If both operands are supplied as 0 or 
-1, logical operators return 0 or -1. The given operation is performed on 
these integers bit-by-bit; i.e., each bit of the result is determined by the 
corresponding bits in the two operands. 
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Thus, it is possible to use logical operators to test bytes for a particular bit 
pattern. For instance, the AND operator may be used to “mask” all but 
one of the bits of a status byte at a machine I/O port. The OR operator 
may be used to “merge” two bytes to create a particular binary value. The 
following examples, all using decimal numbers, demonstrate how the 
logical operators work. 


63 AND 16= 16 


IS AND 14= 14 


-l AND 8=8 


4OR 2=6 


10 OR 10 = 10 


-1 OR -2 =-1 


NOT X = -(X+1) 


63 = binary 111111 and 16= binary 10000, so 63 AND 
16 = 16. 


15 = binary 1111 and 14= binary 1110, so 15 and 14= 
14 (binary 1110). 


-1 = binary 1111111111111111 and 8 = binary 1000, so 
-1 AND 8=8. 


4= binary 100 and 2 = binary 10,so 4OR 2 = 6 (binary 
110). 


10 = binary 1010, so 1010 OR 1010 = 1010 (decimal 
10). 


-1 = binary IIIIIIIIIII11111 and -2 = binary 
1111111111111110,so0-1 OR -2 =-1. The bit comple- 
ment of sixteen zeros is sixteen ones, which is the 
two’s complement representation of -1. 


The two’s complement of any integer is the bit com- 
plement plus one. 
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3.4.5 String Operators 
Strings may be concatenated by using the plus sign (+). For example: 


10 A$=“FILE” : BS=“NAME” 
20 PRINT A$+B$ 
30 PRINT “NEW ”+A$+B$ 


will yield 


FILENAME 
NEW FILENAME 


Strings may be compared using the same relational operators that are used 
with numbers: 


= i < > <= >= 


String comparisons are made by taking one character at a time from each 
string and comparing the ASCII codes. If all the ASCII codes are the 
same, the strings are equal. If the ASCII codes differ, the lower code 
number precedes the higher. If during string comparison the end of one 
string 1s reached, the shorter string is said to be smaller. Leading the 
trailing blanks are significant. 


For example: 


“AA” is less than “AB” 
“FILENAME” is equal to “FILENAME” 
“Xo” is greater than “xX#” 

(because # comes before &) 
“el * is greater than “CL” 

(because of the trailing space) 
“ke” is greater than “KG” 
“SMYTH” is less than “SMYTHE” 
BS is less than “9/12/78” 


(where B$=“8 / 12/78”) 


Thus, string comparisons can be used to test string values or to alphabetize 
strings. All string constants used in comparison expressions must be 
enclosed in quotation marks. 
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3.5 TYPE CONVERSION 


When necessary, Microsoft GW-BASIC will convert a numeric constant 
from one type to another. The following rules and examples apply to 
conversions. 


1. Ifa numeric variable of one type is set equal to a numeric constant 
of a different type, the number will be stored as the type declared 
in the variable name. 


Example: 


10 PERCENT%=23.42 
20 PRINT PERCENT% 


will yield 
23 


2. During expression evaluation, all of the operands in an arithmetic 
or relational operation are converted to the same degree of preci- 
sion as that of the most precise operand. Also, the result of an 
arithmetic operation is returned to this degree of precision. 
arithmetic operation is returned to this degree of precision. 
Examples: 

10 DEDUCTION#=6#/7 
20 PRINT DEDUCTION# 
will yield 
.8571428571428571 


The arithmetic was performed in double precision and the result 
was returned in DEDUCTION# as a double precision value. 


10 DEDUCTION=6# /7 
20 PRINT DEDUCTION 


will yield 
857143 


The arithmetic was performed in double precision, and the result 
is rounded to single precision and returned to DEDUCTION 
(single precision variable), and printed. 


3. Logical operators (see Section 3.4.4) convert their operands to 


integers and return an integer result. Operands must be in the 
range -32768 to 32767 or an “Overflow” error occurs. 
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4. When a floating-point value is converted to an integer, the frac- 
tional portion is rounded. 


Example: 


10 CASH%=55.88 

20 PRINT CASH% 
will yield 

56 


5. If a double precision variable is assigned a single precision value, 
only the first seven digits (rounded) of the converted number will 
be valid. This is because only seven digits of accuracy were sup- 
plied with the single precision value. The absolute value of the 
difference between the printed double precision number and the 
original single precision value will be less than 6.3E-8 times the 
original single precision value. 


Example: 


10 A=2.04 
20 BH=A 
30 PRINT A;B# 


will yield 
2.04 2.039999961853027 


3.6 FUNCTIONS 


GW-BASIC 2.0 incorporates two kinds of functions: intrinsic and user- 
defined. 


3.6.1 Intrinsic Functions 


When a function is used in an expression, it calls a predetermined opera- 
tion that is to be performed on an operand. Microsoft GW-BASIC has 
functional operators that reside in the system, such as SQR (square root) 
or SIN (sine), and these resident functions are called “intrinsic functions”. 


3.6.2 User-Defined Functions 


Microsoft GW-BASIC also allows “user-defined” functions that are writ- 
ten by the programmer. See DEF FN Statement, Section 7.30. 
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3.7 THE KEYBOARD 


The keyboard is divided into three general areas: 


@ Twelve function keys, labeled Fl through F12, are on the up side 
of the keyboard. 


@ The “typewriter” area is in the middle. This is where you find the 
regular letter and number keys. 


@ The numeric keypad, similar to a calculator keyboard, is on the 
right side. 


All the keys, in all three areas of the keyboard, are typematic. That means 
they repeat as long as you hold them down. Each of the keyboard areas are 
explained in more detail below: 


3.7.1 Function Keys 
The function keys can be used: 


@ As “soft keys.” That is, you can set each key to automatically type 
any sequence of characters. In fact, some frequently used com- 
mands have already been assigned to these keys. You may change 
these if you wish. Refer to “KEY Statement”. 


@ As program interrupts through use of the ON KEY statement. See 
“ON KEY(n) Statement”. 


3.7.2 Typewriter Keyboard 

The typewriter area of the keyboard behaves much like a standard type- 
writer. All the letters are there, in their usual places. The numbers 0 
through 9 are on the top row, along with some special characters. 

3.7.3 Numeric Keyboard 


Figures 3-1 through 3-5 illustrate the types of GW-BASIC keyboards. 
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Figure 3-1 APC III Keyboard 





Figure 3-2. Graph 1 Keyboard 





Figure 3-3 Graph 1 Shift Keyboard 
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Figure 3-4 Graph 2 Keyboard 





Figure 3-5 Graph 2 Shift Keyboard 
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Writing Programs a 
Using the GW-BASIC Editor 


GW-BASIC provides two ways to enter and edit text: you can issue an 
EDIT command to place you in edit mode or use the full screen editor. 


4.1 EDIT COMMAND 


The EDIT command places the cursor on a specified line so that changes 
can be made to the line. See EDIT command, Section 7.39. 


4.2 FULL SCREEN EDITOR 


The full screen editor gives you immediate visual feedback, so that pro- 
gram text is entered in a “what you see is what you get” manner. If the user 
has a program listing on the screen, the cursor can be moved to a program 
line, the line edited, and the change entered by pressing the return key. This 
time-saving capability is made possible by special keys for cursor move- 
ment, character insertion and deletion, and line or screen erasure. Specific 
functions and key assignments are discussed in the following sections. 


With the full screen editor, you can move quickly around the screen, 
making corrections where necessary. The changes are entered by placing 
the cursor on the changed line and pressing CRETURN>. 


When input processes are directed from the screen, the user may use the 
full-screen editor features in responding to INPUT and LINE INPUT 
statements. 
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4.2.1 Writing Programs 


You are using the full screen editor any time between the interpreter’s 
“OK” prompt and the execution of a RUN command. Any line of text that 
is entered is processed by the editor. Any line of text that begins with a 
number is considered a program statement. 


It is possible to extend a logical line over more than one physical line by 
continuing typing beyond the last column of the screen. The editor wraps 
the logical line so that it continues on the next physical line. A carriage 
return signals the end of the logical line; when a carriage return is entered, 
the entire logical line is passed to GW-BASIC. Up to 255 characters may 
be present in one logical line. 


Program statements are processed by the editor in one of the following 
ways: 


1. Anew line is added to the program. This occurs if the line number 
is valid (0 through 65529) and at least one non-blank character 
follows the line number. 


2. An existing line is modified. This occurs if the line number 
matches that of an existing line in the program. The existing line is 
replaced with the text of the new line. 


3. Anexisting line is deleted. This occurs if the line contains only the 
line number, and the number matches that of an existing line. 


4. The statements are passed to the command scanner for interpreta- 
tion (i.e., the statement is executed). 


5. An error is produced. 


If an attempt is made to delete a non-existent line, an “Undefined 
line” error message is displayed. 


If program memory is exhausted, and a line is added to the 
program, an “Out of memory” error message 1s displayed, and the 
line is not added. 


More than one statement may be placed on a line. If this is done, the 


statements must be separated by a colon (:). The colon need not be 
surrounded by spaces. 
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4.2.2 Editing Programs 


Use the LIST command to display an entire program or range of lines on 
the screen so that they can be edited with the full screen editor. Text can 
then be modified by moving the cursor to the place where the change is 
needed and then performing one of the following actions: 


. Typing over existing characters 

. Deleting characters to the right of the cursor 
. Deleting characters to the left of the cursor 

. Inserting characters 


Mn & WN — 


. Appending characters to the end of the logical line 


These actions are performed by special keys assigned to the various full 
screen editor functions (see the next section). 


Changes to a line are recorded when a carriage return is entered while the 
cursor is somewhere on that line. The carriage return enters all changes for 
that logical line, and, up to the 255 character line limitation, no matter how 
many physical lines are included and no matter where the cursor is located 
on the line. 


4.2.2.1 SPECIAL PROGRAM EDITOR KEYS 


KEY(S) FUNCTION 


Capital letters and the special characters are dis- 
played by holding down either of the Shift keys 
and pressing the desired key. 


Caps Lock This keyboard does not have a normal Shift Lock 
key. The Caps Lock key is similar to a Shift Lock 
key, but it only gives you capital letters, and will 
not give you the uppershift characters on the 
numeric or other keys. After you press this key, 
you will continue to get capital letters until you 
press it again. You can get lowercase letters when 
in Caps Lock state by pressing and holding one of 
the Shift keys. When you release the Shift key, 
youll go back to Caps Lock state. 
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SPECIAL PROGRAM EDITOR KEYS (Cont’d) 


KEY(S) FUNCTION 


Ctrl The Ctrl key is also used to enter certain codes and 
characters not otherwise available from the key- 
board. 


For example, Ctrl-G is the be// character. When 
this character is printed, the speaker beeps. Note 
how the notation “Ctrl-G” means you press and 
hold the Ctrl key, then press the G key. Then you 
can release both keys. 


You also use the Ctrl key together with other keys 
when you edit programs with the program editor. 


The Alt key enables easy entry of BASIC state- 
ment keywords. This key allows you to type an 
entire BASIC keyword with a single keystroke. 


The BASIC keyword is typed when the Alt key is 
held down while one of the alphabetic keys A-Z is 
pressed. Keywords associated with each letter are 
summarized below. Letters not having reserved 
words are noted by “(no word).” 


NEXT 
OPEN 
PRINT 
(no word) 
RUN 
SCREEN 
THEN 
USING 
VAL 
WIDTH 
XOR 
LOCATE (no word) 
M MID$ (no word) 


The Alt key is also used with the keys on the 
numeric keypad to enter characters not found on 
the keys. This is done by holding down the Alt key 
and typing the three-digit ASCII code for the 
character. 


(no word) 
KEY 


CASH MONMOOW> 
NX XE <CHNZOHVOZ 
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SPECIAL PROGRAM EDITOR KEYS (Cont’d) 


KEY(S) FUNCTION 


Grphl and Grph2 | The Grphl and Grph2 key is used to enter graph- 
ic’s characters not otherwise available from the 
keyboard. 


Ctrl-C or Break Ctrl-C or Break interrupts program execution at 
the next BASIC instruction and returns to BASIC 
command level. It is also used to exit AUTO line 
numbering mode. 


Ctrl-S sends the computer into a pause state. This 
can be used to temporarily halt printing or pro- 
gram listing. The pause continues until Ctrl-S is 
pressed again. 


Backspace or The Backspace key behaves somewhat differently 

Ctrl-H from the Backspace key ona typewriter. It not only 
backspaces, it erases what you’ve typed as well. 
You should use the Cursor Left key to avoid eras- 
ing what you’ve typed. 


Return or Enter The key with the Return or Enter symbol on it is 
or Ctrl-M the carriage return key. You usually have to press 
this key to enter information into the computer. 
We will refer to it as the Enter key from now on. 


There are several important differences between 
this keyboard and a regular typewriter, however. 


Moves the cursor to the upper left-hand corner of 
the screen. 


Shift-Clear Home | Clears the screen and positions the cursor in the 
or Ctrl-L upper left-hand corner of the screen. 
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SPECIAL PROGRAM EDITOR KEYS (Cont’d) 


KEY(S) FUNCTION 


Ctrl-P serves as an on-off switch for any text sent 
to the screen to be also sent to your system printer. 
Press and hold the Ctrl key. Press the P key and 
then release both keys to print the display on the 
printer. Press and release both keys again to stop 
printing display output on the printer. 


ESC or Ctrl-U When pressed anywhere in the line, erases the 
entire logical line from the screen. The line is not 
passed to BASIC for processing. If it is a program 
line, it is not erased from the program in memory. 


TAB or Ctrl-I Moves the cursor to the next tab stop. Tab stops 
ais occur every eight character positions; that is, at 
positions 1, 9, 17, etc. 


When insert mode is off, pressing the Tab key 
moves the cursor over characters until it reaches 
the next tab stop. 


For example, suppose we have the following line: 
10 REM this is a remark 


If we press the Tab key, the cursor will move to the 
ninth position as shown: 


10 REM this is a remark 


If we press the Tab key again, the cursor moves to 
the 17th position on the line: 


10 REM this is a_ remark 


When insert mode is on, pressing the Tab key 
inserts blanks from the current cursor position to 
the next tab stop. Line folding occurs as explained 
under Ins. 


For example, suppose we have this line: 
10 REM this is a remark 


If we press the Ins key and then the Tab key, blanks 
are inserted up to position 17: 


10 REM th is a remark 
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SPECIAL PROGRAM EDITOR KEYS (Cont’d) 


KEY(S) FUNCTION 


Ctrl-G This key is used to beep the speaker. 


Ctrl-Return This key extends logical lines to new physical lines. 
or Ctrl-J A new blank line is added to the last line in the 
current logical line. 


Ctrl-T This key is used to display on/off the soft keys. 
This key is alternating switch. 


Ctrl-W This key deletes the current word starting at the 
(delete word) current cursor position, and ending at the charac- 
ter previous to the next word. 


Ctrl-X This key scrolls down the screen. Previous logical 
line is displayed at the current cursor position. 


Ctrl-Y This key scrolls up the screen. Next logical line is 
displayed at the bottom of the screen. 


Ctrl-Z Clear to the end of the screen from the current 
cursor position. 
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SPECIAL PROGRAM EDITOR KEYS (Cont'd) 


KEY(S) FUNCTION 


Erases to the end of logical line from the current 
cursor position. All physical screen lines are erased 
until the terminating Enter is found. 























Moves the cursor one position left. If the cursor 
advances beyond the left edge of the screen, the 
cursor will move to the right side of the screen on 
the previous line up. 






(Cursor Left) 





— 


(Cursor Right) 


Moves the cursor one position right. If the cursor 
advances beyond the right edge of the screen, the 
cursor will move to the left side of the screen on the 
next line down. 


















t Moves the cursor one position up. 
(Cursor Up) 









| 
(Cursor Down) 


Moves the cursor one position down. 





Shift-) or Ctrl-N Moves the cursor to the end of the logical line. 
Characters typed from this position are added to 


the end of the line. 
















Shift-— or Ctrl-F 
(Next Word) 


Moves the cursor right to the next word. A word is 
defined as a character or group of characters which 
begins with a letter or number. Words are sepa- 
rated by blanks or special characters. So, the next 
word will be the next letter or number to the right 
of the cursor which follows a blank or special 
character. 


For example, suppose we have the following line: 
LINE (L1,LOW2)-(MAX,48) ,3 , BF 
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SPECIAL PROGRAM EDITOR KEYS (Cont’d) 


KEY(S) FUNCTION 


As you can see, the cursor is presently in the middle 
of the word LOW2. If we press Next Word (Shift 
Cursor Right), the cursor will move to the begin- 
ning of the next word, which is MAX: 

LINE (L1,LOW2)-(MAX,48) ,3 , BF 
If we press Next Word again, the cursor will move 
to the next word, which is the number 48: 


LINE (L1,LOW2)-(MAX,48) ,3 , BF 


Shift-— or Ctrl-B Moves the cursor left to the previous word. The 
(Previous Word) previous word will be the letter or number to the 
left of the cursor which is preceded by a blank or 
special character. 
For example, suppose we have: 
LINE (L1,LOW2)-(MAX,48) ,3 , BF 
If we press Previous Word (Shift Cursor Left), the 
cursor moves to the beginning of the word BF: 
LINE (L1,LOW2)-(MAX,48) ,3 , BF 
When we press Previous Word again, the cursor 
moves to the previous word, which is the number 3: 
LINE (L1,LOW2)-(MAX,48) ,3 , BF 
And if we press it twice more, the cursor will back 
up first to the number 48, then to the word MAX: 


LINE (L1,LOW2)-(MAX,48) ,3 , BF 


oy 


Shift-Print This is a special key that causes a copy of what is on 
the screen to be printed on the printer (LPT1:). So, 
if you ever need a hard (printed) copy of what is 
currently being displayed, just press and hold one 
of the Shift keys, and press the PRTSC key. (Note: 
Characters which are unrecognizable by the print- 
er are printed as blanks.) 
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SPECIAL PROGRAM EDITOR KEYS (Cont'd) 


KEY(S) _ FUNCTION 


Ins or Ctrl-R Sets insert mode. If insert mode is off, then press- 
ing this key will turn it on. If insert mode is already 
on, then you will turn it off when you press this 
key. When you’re in insert mode, the cursor covers 
the lower half of the character position. 

































When insert mode is on, characters above and 
following the cursor move to the right as typed 
characters are inserted at the current cursor posi- 
tion. After each keystroke, the cursor moves one 
position to the right. Line folding occurs; that is, as 
characters advance off the right side of the screen 
they return on the left on a subsequent line. 


When insert mode is off, any characters typed 
replace existing characters on the line. 


Besides pressing the Ins key again, insert mode will 
also be turned off when you press any of the cursor 
movement keys or the Enter key. 





Deletes the character at the current cursor posi- 
tion. All characters to the right of the deleted char- 
acter move one position left to fill in the empty 
space. Line folding occurs; that is, if a logical line 
extends beyond one physical line, characters on 
subsequent lines move left one position to fill in the 
previous space, and the character in the first 
column of each subsequent line moves up to the 
end of the preceding line. 


4.2.3 Control Characters 


Table 4-1 lists the hexadecimal codes for the GW-BASIC control charac- 
ters and summarizes their functions. The Control-key sequence normally 
assigned to each function is also listed. 


Individual control functions are described following Table 4-1. 
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Table 4-1 GW-BASIC Control Functions 


Ctrl-A 
Ctrl-B 
Ctrl-C 
Ctrl-D 
Ctrl-E 
Ctrl-F 
Ctrl-G 
Ctrl-H 
Ctrl-I 
Ctrl-J 
Ctrl-K 
Ctrl-L 
Ctrl-M 
Ctrl-N 
Ctrl-O 
Ctrl-P 
Ctrl-Q 
Ctrl-R 
Ctrl-S 
Ctrl-T 
Ctrl-U 
Ctrl-V 
Ctrl-W 
Ctrl-X 
Ctrl-Y 
Ctrl-Z 
Ctrl-[ 


Ctrl-\ 
Ctrl-] 
Ctrl- * 


Ctrl-_ 


Ctrl-DEL 


Ignored 

Move cursor to start of previous word 

Break 

Ignored 

Truncate line (clear text to end of logical line) 

Move cursor to start of next word 

Beep 

Backspace, deleting characters passed over 

Tab (8 spaces) 

Linefeed 

Move cursor to home position 

Clear window 

Carriage return (enter current logical line) 

Append to end of line 

Ignored 

Ignored 

Ignored 

Toggle insert/typeover mode 

Suspend program 

Display function key contents 

Clear logical line 

Ignored 

Delete word 

Display previous program line 

Display following program line 

Clear to end of window 

Ignored or start of control sequence 
(GW-BASIC option) 

Cursor right 

Cursor left 

Cursor up 

Cursor down (underscore) 

Delete character at cursor 





4.2.4 Logical Line Definition with INPUT 


Normally, a logical line consists of all the characters on each of the 
physical lines that make up the logical line. During execution of an INPUT 
or LINEINPUT statement, however, this definition is modified slightly to 
allow for forms input. When either of these statements is executed, the 
logical line is restricted to characters actually typed or passed over by the 
cursor. The insert and delete modes move only characters that are within 
that logical line, and delete mode will decrement the size of the line. 


Insert mode increments the logical line except when the characters moved 
will write over non-blank characters that are on the same physical line but 
not part of the logical line. In this case, the non-blank characters not part 
of the logical line are preserved and the characters at the end of the logical 
line are thrown out. This preserves labels that existed prior to the INPUT 
statement. 


4.2.5 Editing Lines with Syntax Errors 


When a syntax error is encountered during program execution, GW- 
BASIC prints the line containing the error and enters direct mode. You 
can correct the error, enter the change, and reexecute the program. Whena 
line is modified, all files are closed, and all variables are lost. Thus, if the 
user wishes to examine the contents of variables just before the syntax 
error was encountered, the user should print the values before modifying 
the program line. Alternative ways to get to direct mode without erasing 
variable values or closing files are the STOP and END commands. 
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Working with Files 
and Devices 





This chapter discusses the way files and devices are used and addressed in 
GW-BASIC 2.0, and the way information 1s input and output through the 
system. 


5.1 DEFAULT DEVICE 


When a filespec is given (in commands or statements such as FILES, 
OPEN, KILL), the default (current) disk drive is the one that was the 
default in MS-DOS before GW-BASIC was invoked. 


5.2 DEVICE-INDEPENDENT INPUT/OUTPUT 


Microsoft GW-BASIC 2.0 provides device-independent input/output 
that permits flexible approaches to data processing. Using device inde- 
pendent I/O means that the syntax for access is the same for any device. 


The following statements, commands, and functions support device- 
independent I/O (see individual descriptions in Chapter 7): 


BLOAD LOF 
BSAVE MERGE 
CHAIN OPEN 
CLOSE POS 
EOF PRINT 
GET PRINT USING 
INPUT PUT 
INPUTS RUN 
LINE INPUT SAVE 
LIST WIDTH 
LOAD WRITE 
LOC 
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5.3 FILENAMES AND PATHS 


GW-BASIC 2.0 uses MS-DOS 2.0’s enhanced directory structure, allow- 
ing files to be accessed through their pathname. 


5.3.1 Filename Specifications 


File specifications follow MS-DOS 2.0 naming conventions. All filespecs 
may begin with a device specification suchas A: or B: or COM 1: or LPTI1:. 
If no device is specified, the current drive is assumed. The default exten- 
sion .BAS is appended to filenames used in LOAD, SAVE, MERGE and 
RUN <filename>commands, if no period (.) appears in the filespec and if 
the filename is less than nine characters long. 


Examples: 


RUN “NEWFILE.BAS” 
RUN “A:NEWFILE.BAS” 
RUN “KYBD:NEWFILE.BAS” 
SAVE “NEWFILE?” (file is saved with .BAS extension on default 
device) 
5.3.2 Pathnames 


A pathname is a sequence of directory names followed by a simple file- 
name, each separated from the previous one by a backslash (\), and no 
longer than 128 characters. If a device is specified, it must be specified at 
the beginning of the pathname. A simple filename is a sequence of charac- 
ters that can optionally be preceded by a drive designation, be devoid of 
backslashes, and be optionally followed by an extension. 


[<d>:][<directory>]\[<directory...>]\[<filename>] 


ROOT 
GAMES BIN USER ACCOUNTS PROGRAM 
JOE SUE MARY 
Text.txt FORMS Text.txt 
1A 


A Sample Hierarchical Directory Structure 
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In the structure shown above, directories are in all upper-case letters. The 
two entries named Text.txt and the entry named IA are files. 


If a pathname begins with a backslash, MS-DOS searches for the file 
beginning at the root (or tab) of the tree. Otherwise, MS-DOS begins at 
the user’s current directory, known as the working directory, and searches 
downward from there. 


The pathname of Sue’s TEXT.TXT file is \USER\SUE\TEXT.TXT. 


When you are in your working directory, a filename and its corresponding 
pathname may be used interchangeably. Some sample names are: 


\ Indicates the root directory. 


\PROGRAMS Sample directory under the root direc- 
tory containing program files. 


\USER\MARY\FORMS\IA — A typical full pathname. This one 
happens to be a file named 1A in the 
directory named FORMS belonging 
to the subdirectory of USER named 
MARY. 


USER\SUE A relative pathname; it names the file 
or directory SUE in subdirectory 
USER of the working directory. If the 
working directory is the root (\), (\), 
it names \USER\SUE. 


Text.txt Name of a file or directory in the 
working directory. 
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MS-DOS provides special shorthand notations for the working directory 
and the parent directory (one level up) of the working directory: 


MS-DOS uses this shorthand notation to indicate the name of the 
working directory in all hierarchical directory listings. MS-DOS 
automatically creates this entry when a directory is made. 


The shorthand name of the working directory’s parent directory. 
If you type: 
DIR .. 


then MS-DOS will list the files in the parent directory of your 
working directory. 


If you type: 
DIR ..\.. 


then MS-DOS will list the files in the parent’s PARENT direc- 
tory. 


5.3.3 Working with Pathnames in BASIC 


Not only can BASIC provide the ability to access files from other directo- 
ries using pathname approaches, but it can also be used to create, change, 
and remove paths, using the BASIC commands MKDIR, CHDIR, and 
RMDIR. 


The BASIC statement MKDIR “ACCOUNTS” would create a new direc- 
tory, ACCOUNTS, in the working directory of the current drive. 


The BASIC statement CHDIR “B:EXPENSES” would change the cur- 
rent directory on B: to EXPENSES. 


The BASIC statement RMDIR “CLIENTS” would delete an existing 
directory, CLIENTS, as long as that directory was empty of all files with 
the exception of “.” and “..”. 


For further information on handling paths in BASIC, see CHDIR, 
ENVIRON, ENVIRON$, MKDIR, and RMDIR Statements in Chapter 7. 
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5.4 RE-DIRECTION OF STANDARD INPUT 
AND STANDARD OUTPUT 


BASIC can be re-directed to read from standard input and write to 
standard output by providing the input and output filenames on the 
command line: 


BASIC [program name] [<input file] [>output file] 


Note that the characters “<” before the input file and “>” before the 
output file are literally those characters, and not angle brackets indicating 
a required argument. If two greater-than characters (“>>”) appear before 
the output file name, the output is appended to that file. 


Rules: 


L. 


Nn na & W 


When re-directed, all INPUT, LINE INPUT, INPUT$, and 
INKEY$ statements will read from the input file. 


. If the program does not specify a file number in a PRINT state- 


ment, that output is redirected to the declared output file instead 
of the standard output device, the screen. 


. Error messages go to standard output. 

. File input from “KYBD:” still reads from the keyboard. 

. File output to “SCRN:” still outputs to the screen. 

. BASIC will continue to trap keys from the keyboard when the ON 


KEY(n) statement is used. 


. The printer echo key will not cause LPT1: echoing if Standard 


Output has been re-directed. 


. Typing Control-C or Break will cause BASIC to close any open 


files, issue the message “Break in line <line_number>” to stand- 
ard output, and exit BASIC. 


. When input is redirected, BASIC will continue to read from this 


source until an end-of-file character is detected. This condition 
may be tested with the EOF function. If the file is not terminated 
by a Control-Z, or a BASIC input statement tries to read past 
end-of-file, then any open files are closed, the message “Read past 
end” is written to standard output, and BASIC terminates. 
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Examples: 


BASIC MYPROG >DATA.OUT 


Data read by INPUT and LINE INPUT will continue to come 
from the keyboard. Data output by PRINT will go into the file 
DATA.OUT. 


BASIC MYPROG <DATA.IN 


Data read by INPUT and LINE INPUT will come from 
DATA.IN. Data output by PRINT will continue to go to the 
screen. 


BASIC MYPROG <MYINPUT.DAT >MYOUTPUT.DAT 


Data read by INPUT and LINE INPUT will now come from the 
file MYINPUT.DAT and data output by PRINT will go into 
MYOUTPUT.DAT. 


BASIC MYPROG <\SALES\JOHN\TRANS. >>\SALES\SALES.DAT 


Data read by INPUT and LINE INPUT will now come from the 
file \SALES\JOHN\ TRANS. Data output by PRINT will be appended 
to the file \SALES\SALES.DAT. 


5.5 HANDLING FILES 


File I/O procedures for the beginning BASIC user are examined in this 
section. If you are new to BASIC, or if you are encountering file-related 
errors, read through these procedures and program examples to make sure 
you are using all the file statements correctly. 


5-6 


Working with Files and Devices 


5.5.1 Program File Commands 


The following is a review of the commands and statements used in pro- 
gram file manipulation. All file specifications may include the device and 
pathname. 


SAVE <filespec> {[,A:P]} | Writes the program that currently resides 
in memory to the specified file. Option A 
writes the program as a series of ASCII 
characters. With option P, BASIC will 
encode the file in a read-protected format. 


LOAD <filespec> [,R] Loads the program from file into memory. 
The optional R runs the program imme- 
diately. LOAD always deletes the current 
contents of memory and closes all files 
before loading. If R is included, however, 
open data files are kept open. Thus, pro- 
grams can be chained or loaded in sections 
and access the same data files. (LOAD 
FILESPEC>,R and RUN FILESPEC),R 
are equivalent.) 


RUN <dfilespec> [,R] Loads the program from file into memory 
and runs it. RUN deletes the current con- 
tents of memory and closes all files before 
loading the program. If the R option is 
included, however, all open data files are 
kept open. (RUN <filespec>,R and 
LOAD <filespec>,R are equivalent.) 


MERGE <filespec> into Loads the program from file memory out 
but does not delete the current contents of 
memory. The program line numbers in the 
file are merged with the line numbers in 
memory. If two lines have the same number, 
only the line from the file program 1s saved. 
Aftera MERGE command 1s executed, the 
“merged” program resides in memory, and 
BASIC returns to command level. In order 
to successfully MERGE a program, the 
<filespec> must have been saved in 
ASCII format. 
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CHAIN [MERGE ] <filespec> [,[ <line number exp> ] [,ALL] 

[, DELETE <range> ]] 
Where <line number expression> is the 
line number in the new program at which 
the program is to start execution. Passes 
control to the named program, and passes 
the use of the variables and their current 
values to the new program. The user may 
choose to start the new program ona speci- 
fied line, delete some lines, or transfer the 
values of only some of the variables. 


KILL <filespec> Deletes the file from the disk. <filespec> 
can be a program file or a sequential or 
random access data file. 


NAME <old filespec> 
AS <new filespec> Changes the name of a file. NAME AS 
<filespec> can be used with program files, 
random access files, or sequential files. 
Pathnames are not permitted. 


5.5.2 Protecting Program Files 


If you wish to have a program saved in an encoded binary format, use the 
“Protect” option with the SAVE command. For example: 


SAVE “MYPROG”,P 


A program saved this way cannot be listed or edited. You may also want to 
save an unprotected copy of the program for listing and editing purposes. 


5.6 DATA FILES: SEQUENTIAL AND RANDOM ACCESS I/O 


There are two types of disk data files that can be created and accessed bya 
BASIC program: sequential files and random access files. 


5.6.1 Sequential Files 


Sequential files are easier to create than random access files, but are 
limited in flexibility and speed when it comes to locating data. The data 
written to a sequential file is a series of ASCII characters stored, one item 
after another (sequentially), in the order sent. The data is read back 
sequentially, one item after another. 
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The following statements and functions are used with sequential data files 
in sequential order. 


OPEN 
WIDTH 
PRINT# 
PRINT USING# 
WRITE# 
INPUT# 
INPUTS 

LINE INPUT# 
EOF 

LOC 

LOF 

CLOSE 


5.6.1.1 CREATING A SEQUENTIAL FILE 


Program | is ashort program that creates a sequential file, “DATA,” from 
information you input at the keyboard. 
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Program |—Create a Sequential Data File 


10 OPEN “O”,#1,“DATA” 

20 INPUT “NAME”;N$ 

25 IF N$ = “DONE” THEN END 

30 INPUT “DEPARTMENT”;DEPT$ 

40 INPUT “DATE HIRED”;HIREDATE$ 
50 PRINT#1,N$;”,“; DEPT$;”,“; HIREDATE$ 
60 PRINT 

70 GOTO 20 


RUN 


NAME? SAMUEL GOLDWYN 
DEPARTMENT? AUDIO/VISUAL AIDS 
DATE HIRED? 01/12/72 


NAME? MARVIN HARRIS 
DEPARTMENT? RESEARCH 
DATE HIRED? 12/03/65 


NAME? DEXTER HORTON 
DEPARTMENT? ACCOUNTING 
DATE HIRED? 04/27/81 


NAME? STEVEN SISYPHUS 
DEPARTMENT? MAINTENANCE 
DATE HIRED? 08/16/81 


NAME? etc. 


As illustrated in Program 1, the following program steps are required to 
create a sequential file and access the data in it: 


1. OPEN the file in “O” mode. 


2. Write data to the file using the PRINT# statement. (WRITE# can 
be used instead.) 


3. To access the data in the file, you must CLOSE the file and reopen 
it in “I” mode. 

4. Use the INPUT# statement to read data from the sequential file 
into the program. 
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5.6.1.2 READING DATA FROM A SEQUENTIAL FILE 


Now look at Program 2. It accesses the file “DATA” that was created in 
Program | and displays the name of everyone hired in 1981. 


Program 2—Accessing a Sequential File 


10 OPEN“1”,41,“° DATA” 

20 INPUT#1,N$, DEPT$, HIREDATE$ 

30 IF RIGHT$(HIREDATES$,2) = “81” THEN PRINT N$ 
40 GOTO 20 

RUN 


DEXTER HORTON 
STEVEN SISYPHUS 
Input past end in 20 


Program 2 reads, sequentially, every item in the file, and prints the names 
of employees hired in 1981. When all the data has been read, line 20 causes 
an INPUT PAST END error. To avoid this error, use the WHILE... 
WEND control structure, which uses the EOF function to test for the 
end-of-file. The revised program looks like: 


10 OPEN“1”,41,“DATA” 

IS WHILE NOT EOF(1) 

20 INPUT#1,N$, DEPT$,HIREDATE$ 

30 IF RIGHT$(HIREDATES$,2) = “81” THEN PRINT NS 
40 WEND 


A program that creates a sequential file can also write formatted data to 
the disk with the PRINT# USING statement. For example, the statement 


PRINT#1, USING“####.##,”;A,B,C,D 


could be used to write numeric data to the file without explicit delimiters. 
The commas at the end of the format string separate the items in the disk 
file. 


If the user wants commas to appear in the file as delimiters between 
variables, the WRITE statement can be used. For example, the statement 


WRITE 1, A, B$ 


could be used to write these two variables to the file with commas delimit- 
ing them. 
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The LOC function, when used with a sequential file, returns the number of 
sectors that have been written to or read from the file since it was opened. 
A sector is a 128-byte block of data. 


5.6.1.3 ADDING DATA TO A SEQUENTIAL FILE 


If you have a sequential file residing on disk and want to add more data to 
the end of it, you cannot simply open the file in “O” mode and start writing 
data. As soon as you open a sequential file in the output (“O”) mode, you 
destroy its current contents. 


Instead, use the append (“A”) mode. If the file doesn’t already exist, the 
open statement will work exactly as it would if output (“O”) mode had 
been specified. 


The following procedure can be used to add data to an existing file called 
“FOLKS”. 


Program 3—Adding Data to a Sequential File 


110 OPEN “A”,#1,“FOLKS” 

120 REM ADD NEW ENTRIES TO FILE 

130 INPUT “NAME”;N$ 

140 IF N$=“ ” THEN 201 CARRIAGE RETURN EXITS INPUT 
LOOP 

150 LINE INPUT “ADDRESS? ”;ADDR$ 

160 LINE INPUT “BIRTHDAY? ”;BIRTHDATE$ 
170 PRINT#1,N$ 

180 PRINT#1,ADDR$ 

190 PRINT#1,BIRTHDATE$ 

200 GOTO 120 

210 CLOSE 1 


5.6.2 Random Access Files 


Creating and accessing random access files requires more program steps 
than creating and accessing sequential files. However, there are advan- 
tages to using random access files. One advantage is that random access 
files require less room on the disk, since BASIC stores them in a packed 
binary format. (A sequential file is stored as a series of ASCII characters.) 
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The biggest advantage of using random access files is that data can be 
accessed randomly, i.e., anywhere on the disk. However, it is not necessary 
to read through all the information from the beginning of the file, as with 
sequential files. This is possible because the information is stored and 
accessed in distinct units called records, each of which is numbered. 


The statements and functions that are used with random access files are: 


STATEMENTS FUNCTIONS 
OPEN CVD 
FIELD CVI 
GET CVS 
LOC MKS$ 
LOF MKD$ 
LSET MKI$ 
RSET 
PUT 
CLOSE 


5.6.2.1 CREATING A RANDOM ACCESS FILE 
Program 4—Create a Random File 


10 OPEN “R”,#1,“FILE”,32 

20 FIELD #1,20 AS N$, 4 AS A$, 8 AS P$ 
30 INPUT “2-DIGIT CODE”;CODE% 
40 INPUT “NAME”;PERSON$ 

50 INPUT “AMOUNT”; AMOUNT 

60 INPUT “PHONE”; TELELPHONE$ 
65 PRINT 

70 LSET N$=PERSON$ 

80 LSET A$=MKS$(AMOUNT) 

90 LSET P$=TELEPHONE$ 

100 PUT #1,CODE% 

110 GOTO 30 
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As illustrated by Program 4, the following program steps are required to 
create a random access file. 


1. OPEN the file for random access (“R” mode). The following 
example specifies a record length of 32 bytes. If the record length 
is not specified, the default is 128 bytes unless it was set to another 
value with the /I/S: switches when invoking BASIC (see Chapter 
2 for details). 


Example: 
OPEN “R”, 1,“FILE”,32 


2. Use the FIELD statement to allocate space in the random buffer 
for the variables that will be written to the random access file. 


Example: 
FIELD #1, 20 AS N$, 4 AS ADDR$, 8 AS P$ 


3. Use LSET to move the data into the random access buffer. 
Numeric values must be made into strings when placed in the 
buffer. To do this, use the “make” functions: MKI$ to make an 
integer value into a string, MKS$ to make a single precision value 
into a string, and MKD$ to make a double precision value into a 
string. 

Example: 


LSET N$=X$ 
LSET ADDR$=MKS$(AMT) 
LSET P$ =TEL$ 


4. Write the data from the buffer to the disk using the PUT state- 
ment. 


Example: 
PUT #1,CODE% 
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Program 4 takes information that is input at the terminal and writes it toa 
random access file. Each time the PUT statement is executed, a record is 
written to the file. The two-digit code that is input in line 30 becomes the 
record number. 


NOTE 


Do not use a fielded string variable in 
an INPUT or LET statement. Doing 
so causes that variable to be rede- 
clared; BASIC will no longer asso- 
ciate that variable with the file buffer, 
but with the new program variable. 


5.6.2.2 ACCESSING A RANDOM ACCESS FILE 


Program 5 accesses the random access file “FILE” that was created in 
Program 4. By entering a three-digit code at the keyboard terminal, the 
information associated with that code is read from the file and displayed. 


Program 5—Access a Random File 


10 OPEN “R”,#1,“FILE”,32 

20 FIELD #1, 20 AS N$, 4 AS A$, 8 AS P$ 
30 INPUT “2-DIGIT CODE”;CODE% 

40 GET #1, CODE% 

50 PRINT N$ 

60 PRINT USING “$S###.##";CVS(A$) 

70 PRINT P$:PRINT 

80 GOTO 30 
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The following program steps are required to access a random access file: 


1. OPEN the file in “R” mode. 
Example: 
OPEN “R”, 1,“FILE”,32 


2. Use the FIELD statement to allocate space in the random access 
buffer for the variables that will be read from the file. 


Example: 
FIELD #1 20 AS N$, 4 AS A$, 8 AS P$ 


NOTE 


In a program that performs both 
input and output on the same random 
access file, you can often use just one 
OPEN statement and one FIELD 
statement. 


3. Use the GET statement to move the desired record into the 
random access buffer. 


Example: 
GET #1,CODE% 


4. The data in the buffer can now be accessed by the program. 
Numeric values that were converted to strings by the MKS$§, 
MKD$ or MKI§ statements must be converted back to numbers 
using the “convert” functions: CVI for integers, CVS for single 
precision values, and CVD for double precision values. The 
MKI$ and CVI processes mirror each other, the former convert- 
ing a number into a format for storage in random files, the latter 
converting the random file storage into a format usable by the 
program. 


Example: 


PRINT N$ ‘ 
PRINT CVS(A$) _— 
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The LOC function, when used with random access files, returns the 
“current record number.” The current record number is the last record 
number that was used in a GET or PUT statement. For example, the 
statement 


IF LOC(1) > 50 THEN END 


ends program execution if the current record number in file#1 is greater 
than 50. 


5.6.2.3 RANDOM FILE OPERATIONS 


Program 6 is an inventory program that illustrates random file access. 
Program 6—Inventory 


120 OPEN“R”,#1,“INVEN.DAT”,39 

125 FIELD#1,1 AS F$,30 AS D$, 2 AS Q$,2 AS R$,4 AS P$ 

130 PRINT:PRINT “FUNCTIONS:”:PRINT 

135 PRINT “1,INITIALIZE FILE” 

140 PRINT “2, CREATE A NEW ENTRY” 

150 PRINT “3, DISPLAY INVENTORY FOR ONE PART” 

160 PRINT “4,ADD TO STOCK” 

170 PRINT “5,SUBTRACT FROM STOCK” 

180 PRINT “6, DISPLAY ALL ITEMS BELOW REORDER 
LEVEL” 

220 PRINT:PRINT:INPUT“FUNCTION”; FUNCTION 

225 IF (FUNCTION < 1) OR(FUNCTION > 6) THEN PRINT 
“BAD FUNCTION NUMBER”:GO TO 130 

230 ON FUNCTION GOSUB 900,250,390,480,560,680 

240 GOTO 220 

250 REM ** BUILD NEW ENTRY ** 

260 GOSUB 840 

270 IF ASC(F$)< >255 THEN INPUT “OVER WRITE”; ADDRS: 
IF ADDR$< >“Y” THEN RETURN 

280 LSET F$ =CHRS(O) 

290 INPUT “DESCRIPTION”; DESCRIPTION$ 

300 LSET D$=DESCRIPTION$ 

310 INPUT “QUANTITY IN STOCK”;QUANTITY% 

320 LSET Q$=MKI$(QUANTITY%) 

330 INPUT “REORDER LEVEL”; REORDER% 

340 LSET R$=MKI$(REORDER%) 

350 INPUT “UNIT PRICE”:PRICE 
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360 LSET P$=MKS$(PRICE) 
370 PUT#1,PART% 
380 RETURN 
390 REM ** DISPLAY ENTRY ** 
400 GOSUB 840 
410 IF ASC(F$)=255 THEN PRINT “NULL ENTRY”:RETURN 
420 PRINT USING “PART NUMBER ###”;PART% 
430 PRINT D$ 
440 PRINT USING “QUANTITY ON HAND #####”;CV1(Q$) 
450 PRINT USING “REORDER LEVEL #####”:CVS(R$) 
460 PRINT USING “UNIT PRICE $$##.##”;CVS(P$) 
470 RETURN 
480 REM ADD TO STOCK 
490 GOSUB 840 
500 IF ASC(F$)=255 THEN PRINT “NULL ENTRY”:RETURN 
510 PRINT D$:INPUT “QUANTITY TO ADD ”;ADDITIONAL% 
520 Q%=CV1(Q$)tADDITIONAL% 
530 LSET Q$=MKI$(Q%) 
540 PUT#1,PART% 
550 RETURN 
560 REM REMOVE FROM STOCK 
570 GOSUB 840 
580 IF ASC(F$)=255 THEN PRINT “NULL ENTRY”:RETURN 
590 PRINT D$ 
600 INPUT “QUANTITY TO SUBTRACT”;LESS% 
610 Q%=CVI(Q$) 
620 IF (Q%-LESS%)<O THEN PRINT “ONLY”:Q%;” 
IN STOCK”:GOTO 600 
630 Q%=Q%-LESS% 
640 IF Q%=<CVI(R$) THEN PRINT “QUANTITY NOW”:Q%; 
“ REORDER LEVEL”:CVI(R$) 
650 LSET Q$=MKI$(Q%) 
660 PUT#1,PART% 
670 RETURN 
680 DISPLAY ITEMS BELOW REORDER LEVEL 
690 FOR I=1 TO 100 
710 GETH#I,I ‘ 
720 IF CVI(Q$)<CVI(R$) THEN PRINT D$;” QUANTITY”: ~ 
CV1(Q$) TAB(50) “REORDER LEVEL”:CVI(R$) 
730 NEXT I 
740 RETURN 
840 INPUT “PART NUMBER”:PART % 
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850 IF(PART%<1)OR(PART%>100) THEN PRINT “BAD PART 
NUMBER”: GOTO 840 ELSE GET#1,PART%:RETURN 

890 END 

900 REM INITIALIZE FILE 

910 INPUT “ARE YOU SURE”:CONFIRMS: 
IF CONFIRM$< >“Y” THEN RETURN 

920 LSET F$=CHR$(255) 

930 FOR I=1 TO 100 

940 PUT#I,I 

950 NEXT I 

960 RETURN 


In this program, the record number is used as the part number. It is 
assumed the inventory will contain no more than 100 different part 
numbers. Lines 900-960 initialize the data file by writing CHR$(255) as the 
first character of each record. This is used later (line 270 and line 500) to 
determine whether an entry already exists for that part number. 


Lines 130-220 display the various inventory functions that the program 
performs. When you type in the desired function number, line 230 
branches to the appropriate subroutine. 


5.7 BASIC AND CHILD PROCESSES 


Through the use of the SHELL statement, GW-BASIC 2.0 is able to use 
one of the most powerful features of MS-DOS: the ability to create child 
processes. SHELL enables the user to run part of a BASIC program, 
temporarily exit to MS-DOS to perform a specified function, and return 
to the BASIC program at the statement after the SHELL statement to 
proceed with the rest of the program. 


BASIC will produce a child program when it uses the SHELL statement. 
It is not possible for BASIC to totally protect itself from its children. When 
a SHELL statement is executed, many things may be going on. For 
example, files may be OPEN and devices may be in use. It is advisable for 
programmers to thoroughly read about the SHELL Statement, Chapter 7, 
before using this powerful statement. 
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Chapter 6 





Using Advanced 
Features 


6.1 ASSEMBLY LANGUAGE SUBROUTINES 


You may call assembly language subroutines from your GW-BASIC 2.0 
program with the USR function or the CALL or CALLS statement. 


It is recommended that you use the CALL or CALLS statement for 
interfacing 8086 machine language programs with GW-BASIC 2.0. These 
statements are more readable and can pass multiple arguments. In addi- 
tion, the CALL statement is compatible with more languages than its 
alternative, the USR function. 


6.1.1 Memory Allocation 


Memory space must be set aside for an assembly language subroutine 
before it can be loaded. To do so, use the / M: switch during start-up. The 
/M: switch sets the highest memory location to be used by GW-BASIC 
2.0. 


In addition to the GW-BASIC 2.0 code area, GW-BASIC 2.0 uses up to 
64K of memory beginning at its data (DS) segment. 


If more stack space is needed when an assembly language subroutine 1s 
called, you can save the GW-BASIC 2.0 stack and set up a new stack for 
use by the assembly language subroutine. The GW-BASIC 2.0 stack must 
be restored, however, before you return from the subroutine. 


The assembly language subroutine can be loaded into memory in several 
ways, the most simple being to use the BLOAD command (see BLOAD 
Command, Section 7.6). Also, the user could SHELL a program that 
exits, but stays resident, leaving the linked, relocated image in memory. As 
a third choice, the user could execute a program that exits but stays 
resident, and then run BASIC. 
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The following guidelines must be observed if you choose to BLOAD, or 
read and poke, an EXE file into memory: 


1. Make sure the subroutines do not contain any long references, 
address offsets that exceed 64K, or that take the user out of the 
code segment. These long references require handling by the EXE 
loader. 


2. Skip over the first 512 bytes (the header) of the linker’s output file 
(EXE), then read in the rest of the file. 


6.1.2 Internal Representation 


The following section describes the internal representation of numbers in 
GW-BASIC. Knowledge of these arrangements is critical for many 
assembly language programming routines. 


Single Precision - 24 bit mantissa 





where loman = the low mantissa 


S = the sign 
himan = the high mantissa 
exp = the exponent 
man = himan.:...:loman 


- If <exp> =0,then <number> = 0. 
- If <exp> <> 0, then the mantissa is normalized and 


<number> = <sgn> *.1 <man> * 2 ** ( <exp> -80h) 
That is, in single precision (hex notation - bytes low to high) 


00000080 
00008080 


How 
nn 


-.5 


Double Precision - 56 bit mantissa 


Efecaseed 





6.1.3 CALL Statement 


The CALL statement is the recommended way of interfacing 8086 
machine language subroutines with GW-BASIC 2.0. Do not use the USR 
function unless you are running previously written subroutines that 
already contain USR functions. 


The syntax of the CALL statement is: 
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CALL <variable name> [(<argument list>)] 


where <variable name> contains the offset into the current segment 
that is the starting point in memory of the subroutine being called. 
The current segment is either the default, or that which has been 
defined by a DEF SEG statement. 


<argument list> contains the variables or constants, separated by 
commas, that are to be passed to the subroutine. 


Invoking the CALL statement causes the following to occur: 


1. For each argument in the argument list, the two-byte offset of the 
argument’s location within the BASIC segment is pushed onto the 


stack. 


2. Control is transferred to the subroutine with an 8086 long call to 
the segment address given in the last DEF SEG statement and the 
offset given in <variable name>. 


Figures 6-1 and 6-2 illustrate the state of the stack at the time the CALL 
statement is executed, and the condition of the stack during execution of 
the called subroutine, respectively. 


high 
addresses 


ms) 


KF OQ ® 
- oer peoaon 


low 
addresses 


return segment address 
return offset 









SP+4+(2*n) 
Each argument is a 2-byte 
pointer into memory 


SP+6 


SP+4 
SP+2 
SP <«——— stack pointer 
(SP register 
contents) 


Figure 6-1 Stack Layout when CALL Statement Is Activated 
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After the CALL statement has been activated, the subroutine has control. 
Arguments may be referenced by moving the stack pointer (SP) to the base. 
pointer (BP) and adding a positive offset to BP. 


high 
addresses 
argument 0 
argument | 
E Absent if any argument is 
referenced within a nested 
procedure 
argument n 
return segment address | <———- Absent in local procedure 
return offset : 
Cc <= Stack pointer 
S oO (SP register 
t u contents) 
. i Local variables 
: : (data pushed on 
. stack) 
r 
This space may be 
used during procedure Stack point may change 
execution during procedure execution 
low 
addresses 





Figure 6-2 Stack Layout during Execution of a CALL Statement 
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Observe the following rules when coding a subroutine: 


1. The called routine must preserve segment registers DS, ES, SS, 
and the base pointer (BP). If interrupts are disabled in the routine, 
they must be enabled before exiting. The stack must be cleaned up 
on exit. 


2. The called program must know the number and length of the 
arguments passed. The following routine shows an easy way to 
reference arguments: 


PUSH BP 

MOV BP,SP 

ADD BP, (2*number of arguments)+4 
Then: 


argument 0 is at BP 
argument | is at BP-2 
argument n is at BP-2*n 


(number of arguments = n+1) 


3. Variables may be allocated either in the code segment or on the 
stack. Be careful not to modify the return segment and offset 
stored on the stack. 


4. The called subroutine must clean up the stack. A preferred way to 
do this is to perform a RET <n> statement (where <n> is two 
times the number of arguments in the argument list) to adjust the 
stack to the start of the calling sequence. 


5. Values are returned to GW-BASIC 2.0 by including in the argu- 
ment list the name of the variable that will receive the result. The 
internal format for numbers in GW-BASIC is discussed in “Inter- 
nal Representation,” Section 6.1.2. 
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6. If the argument is a string, the argument’s offset points to 3 bytes 
which, as a unit, are called the “string descriptor.” Byte 0 of the 
string descriptor contains the length of the string (0 to 255). Bytes 
1 and 2, respectively, are the lower and upper 8 bits of the string 
starting address in string space. 


WARNING 


If the argument is a string literal in the 
program, the string descriptor will 
point to program text. Be careful not 
to alter or destroy your program this 
way. To avoid unpredictable results, 
add +”” to the string literal in the 
program. For example, use 


20 A$ _ “BASIC”,”” 


This will force the string literal to be 
copied into string space. Then the 
string may be modified without affect- 
ing the program. 


7. The contents of a string may be altered by user routines, but the 
descriptor must not be changed. 


Do not write past the end-of-string. GW-BASIC 2.0 cannot cor- 
rectly manipulate strings if their lengths are modified by external 
routines. 


8. Data areas needed by the routine must be allocated either in the 
CODE segment of the user routine or on the stack. It is not 
possible to declare a separate data area in the user assembler 
routine. 


Example of CALL statement: 
100 DEF SEG=&H8000 


110 FO0O=&H7FA 
120 CALL F00(A,B$,C) 
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Line 100 sets the segment to 8000 Hex. The value of variable F00 is added 
into the address as the low word after the DEF SEG value is left shifted 4 
bits. Here, the long call to F00 will execute the subroutine at location 
8000:7FA Hex (absolute address 807FA Hex). 


The following sequence in 8086 assembly language demonstrates access to 
the arguments passed. The returned result is stored in the variable ’C’. 


PUSH 
MOV 
ADD 
MOV 
MOV 
MOV 


MOV 
MOV 
MOVS 
POP 
RET 


BP ;Set up pointer to arguments 

BP,SP 

BP,(4+2*3) 

BS,[BP-2] ;Get address of B$ descriptor 

CL[BX] ;Get length of B$ in CL 

DX, 1[BX] ;Get addr of B$ text in DX 

SI,[BP] ;Get address of ’A’ in SI 

DI[BP-4] ;Get pointer to ’C’ in DI 

WORD ‘Store variable ’A’ in ’C’ 

BP ;Restore pointer 

6 ‘Restore stack, return 
NOTE 


The called program must know the 
variable type for the numeric argu- 
ments passed. In the previous exam- 
ple, the instruction 


MOVS WORD 


will copy only two bytes. This is fine if 
variables A and C are integer. You 
would have to copy four bytes if the 
variables were single precision format 
and copy 8 bytes if they were double 
precision. 
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6.1.4 CALLS Statement 


The CALLS statement should be used to access subroutines that were 
written using MS-FORTRAN calling conventions. CALLS works just 
like CALL, except that with CALLS the arguments are passed as seg- 
mented addresses, rather than as unsegmented addresses. 


Because MS-FORTRAN routines need to know the segment value for 
each argument passed, the segment is pushed and then the offset is also 
pushed. For each argument, four bytes are pushed rather than 2, as in the 
CALL statement. Therefore, if your assembler routine uses the CALLS 
statement, nin the RET <n> statement is four times the number of 
arguments. 


6.1.5 USR Function 


Although using the CALL statement is the recommended way of calling 
assembly language subroutines, the USR function is also available for this 
purpose. This ensures compatibility with older programs that contain 
USR functions. 


USR[<digit>] [(<argument>)] 


where <digit> is from0to 9. <digit> specifies which USR routine 
is being called. If <digit> is omitted, USRO is assumed. 


<argument> is any numeric or string expression. Arguments are 
discussed in detail in the following paragraphs. 


In the GW-BASIC 2.0 Interpreter, a DEF SEG statement must be exe- 
cuted prior to a USR function call to assure that the code segment points 
to the subroutine being called. The segment address given inthe DEF SEG 
statement determines the starting segment of the subroutine. 


For each USR function, a corresponding DEF USR statement must be 
executed to define the USR function call offset. This offset and the 
currently active DEF SEG address determine the starting address of the 
subroutine. 
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When the USR function call is made, register AL contains a value that 
specifies the type of argument that was given. The value in AL may be one 
of the following: 


VALUEIN AL TYPE OF ARGUMENT 
2 Two-byte integer (two’s complement) 
3 String 
4 Single precision floating-point number 
8 Double precision floating-point number 


If the argument is a number, the BX register points to the Floating-Point 
Accumulator (FAC) where the argument is stored. 


If the argument is an integer: 


FAC-2 contains the upper 8 bits of the integer. 
FAC-3 contains the lower 8 bits of the integer. 


For versions of GW-BASIC 2.0 that use binary floating-point: 


FAC is the exponent minus 128, and the binary point is to the left of 
the most significant bit of the mantissa. 
FAC-1 contains the highest 7 bits of mantissa with leading | sup- 
pressed (implied). Bit 7 is the sign of the number (0 = positive, | = 
negative). 

If the argument is a single precision floating-point number: 


FAC-2 contains the middle 8 bits of mantissa. 
FAC-3 contains the lowest 8 bits of mantissa. 


If the argument is a double precision floating-point number: 


FAC-7 through FAC-4 contain four more bytes of mantissa 
(FAC-7 contains the lowest 8 bits). 


If the argument is a string, the DX register points to 3 bytes which, as a 
unit, are called the “string descriptor.” Byte 0 of the string descriptor 
contains the length of the string (0 to 255 characters). Bytes |.and 2, 
respectively, are the lower and upper 8 bits of the string starting address in 
the GW-BASIC 2.0 data segment. 
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WARNING 


If the argument is a string literal in the 
program, the string descriptor will 
point to program text. Be careful not 
to alter or destroy the program this 
way. 


Usually, the value returned by a USR function is the same type (integer, 
string, single precision, or double precision) as the argument that was 
passed to it. 


GW-BASIC 2.0 has extended the USR function interface to allow calls to 
MAKINT and FRCINT. This allows access to these routines without 
giving their absolute addresses. The address ES:BP is used as an indirect 
far pointer to the routines FRCINT and MAKINT. 


To call FRCINT from a USR routine use CALL DWORD ES:[BP]. To 
call MAKINT from a USR routine use CALL DWORD ES:[BP+4]. 


Example: 


110 DEF USRO=&H8000 ’Assumes decimal argument / M:32767 
120 X= 5 

130 Y = USRO(X) 

140 PRINT Y 


The type (numeric or string) of the variable receiving the function call must 
be consistent with that of the argument used. 


6.2 EVENT TRAPPING 


Event trapping allows a program to transfer control to a specific program 
line when a certain event occurs. Control is transferred as if a GOSUB 
statement had been executed to the trap routine starting at the specific line 
number. The trap routine, after servicing the event, executes a RETURN 
statement that causes the program to resume execution at the place where 
it was when the event trap occurred. 


The events that can be trapped are receipt of characters from a communi- 
cations port (ON COM), detection of certain keystrokes (ON KEY), time 
passage (ON TIMER), emptying of the background music queue (ON 
PLAY), joystick trigger activation (ON STRIG), and lightpen activation 
(ON PEN). 


6-10 


Using Advanced Features 


This section gives an overview of event trapping. For more details on 
individual statements, see Chapter 7. 


Event trapping is controlled by the following statements: 


<event specifier> ON to turn on trapping 
<event specifier> OFF to turn off trapping 
<event specifier> STOP to temporarily turn off trapping 


where <event specifier> is one of the following: 


COM (1) where | is the number of the communications channel. 


Typically, the COM trap routine will read an entire mes- 
sage from the COM port before returning. We do not 
recommend using the COM trap for single character 
messages because at high baud rates the overhead of 
trapping and reading for each character may allow the 
interrupt buffer for COM to overflow. 


KEY (n) where n is a trappable key number. Trappable keys are 
numbered | through 22. 


Note that KEY (n) ON is not the same statement as KEY 
ON. KEY (n) ON sets an event trap for the specified key. 
KEY ON displays the values of the function keys on the 
twenty-fifth line of the screen (see Sections 7.67 and 7.68). 


When the GW-BASIC Interpreter is in direct mode func- 
tion keys maintain their standard meanings. 


When a key is trapped, that occurrence of the key is 
destroyed. Therefore, you cannot subsequently use the 
INPUT or INKEY$ statements to find out which key 
caused the trap. So if you wish to assign different func- 
tions to particular keys, you must set up a different 
subroutine for each key, rather than assigning the various 
functions within a single subroutine. 


PEN Since there is only one lightpen, no number is given when 


PEN trapping is enabled. For discussion of PEN used as 
a function, see Section 7.110. 
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TIMER ON TIMER(n), where (n) is a numeric expression repre- 
| senting a number of seconds. The ON TIMER statement 
can be used to perform background tasks at defined 

intervals. 


PLAY ON PLAY(n), where (n) is a number of notes left in the 
music buffer. The ON PLAY statement is used to retrieve 
more notes from the background music queue, to permit 
continuous background music during program execu- 
tion. 


STRIG (n) where n is the number of the joystick trigger. For most 
machines, the range for n is 0 through 6. 


For discussion of STRIG used as a function, see Section 
7.150. 


6.2.1 ON GOSUB Statement 


The ON GOSUB statement sets up a line number for the specified event 
trap. The format is: 


ON <cevent specifier> GOSUB <line number> 
A <line number> of zero disables trapping for that event. 


When an event is ON and if a non-zero line number has been specified in 
the ON GOSUB statement, every time GW-BASIC starts a new statement 
it will check to see if the specified event has occurred (e.g., the lightpen has 
been struck or a COM character has come in). When an event is OFF, no 
trapping takes place, and the event is not remembered even if it takes place. 


When an event is stopped (<event specifier> STOP), no trapping takes 
place, but the occurrence of an event is remembered so that an immediate 
trap will take place when an <event specifier> ON statement is executed. 


When atrap is made for a particular event, the trap automatically causes a 
STOP on that event, so recursive traps can never occur. A return from the 
trap routine automatically executes an ON statement unless an explicit 
OFF has been performed inside the trap routine. 


Note that once an error trap takes place, all trapping is automatically 


disabled. In addition, event trapping will never occur when GW-BASIC is 
not executing a program. 


6-12 


Using Advanced Features 


6.2.2 RETURN Statement 


When an event trap is in effect, a GOSUB statement will be executed as 
soon as the specified event occurs. For example, the statement 


ON PEN GOSUB 1000 


specifies that the program go to line 1000 as soon as the pen is used. If a 
simple RETURN statement is executed at the end of this subroutine, 
program control will return to the statement following the one where the 
trap occurred. When the RETURN statement is executed, its correspond- 
ing GOSUB return address is cancelled. 


GW-BASIC includes the RETURN <line number> enhancement, which 
lets processing resume at a definable line. Normally, the program returns 
to the statement immediately following the GOSUB statement when the 
RETURN statement is encountered. However, RETURN <line number> 
enables the user to specify another line. If not used with care, however, this 
capability may cause problems. Assume, for example, that your program 
contains: 


10 ON PEN GOSUB 1000 

20 FOR I= 1 TO 10 

30 PRINT I 

40 NEXT I 

50 REM NEXT PROGRAM LINE 


200 REM PROGRAM RESUMES HERE 
1000 ’FIRST LINE OF SUBROUTINE 


1050 RETURN 200 


If the pen is activated while the FOR/NEXT loop is executing, the 
subroutine will be performed, but program control will return to line 200 
instead of completing the FOR/ NEXT loop. The original GOSUB entry 
will be cancelled by the RETURN statement, and any other GOSUB, 
WHILE, or FOR (e.g., an ON STRIG statement) that was active at the 
time of the trap will remain active. But the current FOR context will also 
remain active, and a “FOR without NEXT” error may result. 








Chapter 7 


Basic Commands, 
Functions and Statements 





7.1 ABS FUNCTION 
Syntax: 
ABS(X) 
Purpose: 
To return the absolute value of the expression X. 
Example: 


PRINT ABS(7*(-5)) 
will yield 
35 
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7.2 ASC FUNCTION 
Syntax: 

ASC(XS) - 
Purpose: 


To return a numerical value that is the ASCII code for the first character of 
the string X$. (See Appendix A for ASCII codes.) 


Remarks: 
If X$ is null, an “Illegal function call” error is returned. 


Example: 


10 X$=“TEST” 

20 PRINT ASC(X$) 
will yield 

84 


See the CHR§ function, Section 7.13, for details on ASCII-to-string 
conversion. 
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7.3 ATN FUNCTION 
Syntax: 

ATN(X) 
Purpose: 


To return the arctangent of X, where X is in radians. Result is in the range 
-pi/2 to pi/2 radians. 


Remarks: 
The expression X may be any numeric type, but the default evaluation of 


ATN is performed in single precision. This may be overridden if the /D 
switch is used when invoking GW-BASIC 2.0. 


Example: 
10 LET X = 3 
20 PRINT ATN(X) 
will yield 
1.249046 
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7.4 AUTO COMMAND 
Syntax: 
AUTO [<line number> [,<increment>]] - 
Purpose: 
To automatically generate line numbers during program entry. 
Remarks: 


AUTO begins numbering at <line number> and increments each subse- 
quent line number by <increment>. The default for both values is 10. If 
<line number> is followed by a comma but <increment> is not 
specified, the last increment specified in an AUTO command 1s assumed. 


If AUTO generates a line number that is already being used, an asterisk is 
printed after the number to warn the user that any input will replace the 
existing line. However, typing a carriage return immediately after the 
asterisk will save the existing line and generate the next line number. 


If the cursor is moved to another line on the screen, numbering will resume 
there. 


AUTO is terminated by typing the Break or Ctrl-C key. The line in which 
the Break or Ctrl-C key is typed will not be saved. After the Break or 
Ctrl-C key is typed, Microsoft GW-BASIC returns to command level. 


Example: 


AUTO 100,50 Generates line numbers 100, 150, 200.... 
AUTO Generates line numbers 10, 20, 30, 40.... 
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7.5 BEEP STATEMENT 
Syntax: 

BEEP 
Purpose: 
To sound the speaker. 
Remarks: 


The BEEP statement sounds the ASCII bell character. This statement has 
the same effect as PRINT CHR§(7). 


Example: 


20 IF X < 20 THEN BEEP 
This example executes a beep when X is less than 20. 
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7.6 BLOAD COMMAND 
Syntax: 
BLOAD <filespec> [,<offset>] 


The device designation portion of the filespec is optional. The filename, 
not including the device designation, may be | to 8 characters long. 


<offset> is a numeric expression returning an unsigned integer in the 
range 0 to 65535. This is the offset address at which loading is to start in the 
segment declared by the last DEF SEG statement. 


Purpose: 
To load a specified memory image file into memory from any input device. 
Remarks: 


The BLOAD statement allows a program or data that has been saved as a 
memory image file to be loaded anywhere in memory. A memory image 
file is a byte-for-byte copy of what was originally in memory. See BSAVE 
Command, in Section 7.7, for information about saving memory image 
files. 


If the offset is omitted, the segment address and offset contained in the file 
(i.e., the address specified by the BSAVE statement when the file was 
created) are used. Therefore, the file is loaded into the same location from 
which it was saved. 
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If offset is specified, the segment address used is the one given in the most 
recently executed DEF SEG statement. If no DEF SEG statement has 
been given, the GW-BASIC data segment will be used as the default 
(because it is the default for DEF SEG). 


CAUTION 


BLOAD does not perform an address 
range check. It is therefore possible to 
load a file anywhere in memory. The 
user must be careful not to load over 
GW-BASIC or the operating system. 


Example: 
10 ’Load subroutine at 60:F000 
20 DEF SEG=&H6000 ’Set segment to 6000 Hex 
30 BLOAD“PROGI1”,&HF000 "Load PROG! 


This example sets the segment address at 6000 Hex and loads PROG] at 
F000. 


Basic Commands, Functions and Statements 


7.7 BSAVE COMMAND 
Syntax: 
BSAVE <filespec>,<offset>,<length> _— 


The device designation portion of the filespec is optional. The filename, 
not including the device specification, must be | to 8 characters long. 


<offset> is a numeric expression returning an unsigned integer in the 
range 0 to 65535. This is the offset address to start saving from in the 
segment declared by the last DEF SEG statement. 


<length> is a numeric expression returning an unsigned integer in the 
range | to 65535. This is the length in bytes of the memory image file to be 
saved. 


Purpose: 


To transfer the contents of the specified area of memory to any output 
device. | 


Remarks: 


The <filespec>, <offset>, and <length> are required in the syntax. 


The BSAVE command allows data or programs to be saved as memory 
image files on disk or cassette. A memory image file is a byte-for-byte copy 
of what is in memory. 


If the offset is omitted, a “Bad file name” error message is issued and the 
Save is terminated. A DEF SEG statement must be executed before the 
BSAVE. The last known DEF SEG address will be used for the save. 


If length is omitted, a “Bad file name” error message is issued and the save 
is terminated. 


Example: 


10 "Save PROG! 
20 DEF SEG=&H6000 
30 BSAVE“PROGI1”, & HF000,256 


This example saves 256 bytes starting at 6000:FO000 in the file PROGI. 
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7.8 CALL STATEMENT 
Syntax: 
CALL <variable name> [(<argument list>)] 
where <variable name> contains an address that is the starting point in 
memory of the subroutine. <variable name> may not be an array vari- 


able name. 


<argument list> contains the arguments that are passed to the external 
subroutine. <argument list> may contain only variables. 


Purpose: 


To call an assembly language subroutine or a compiled routine written in 
another high level language. 


Remarks: 


The CALL statement is one way to transfer program flow to an external 
subroutine. (See also the USR function, Section 7.162.) 


See Section 6.1.3, CALL Statement, for a detailed discussion of calling 
sequences. 


Example: 


110 MYROUT=&HD000 
120 CALL MYROUT(I,J,K) 
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7.9 CALLS STATEMENT 


The CALLS statement is just like CALL, except that the segmented 
addresses of all arguments are passed. (CALL passes unsegmented 
addresses.) CALLS should be used when accessing routines written with 
the FORTRAN calling convention. All FORTRAN parameters are call- 
by-reference segmented addresses. 


CALLS uses the segment address defined by the most recently executed 
DEF SEG statement to locate the routine being called. 
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7.10 CDBL FUNCTION 
Syntax: 
CDBL(X) 
Purpose: 
To convert X to a double precision number. 


Example: 


10 LET PI = 22/7 
20 PRINT PI,CDBX(PI) 


will yield 
3.142857 3.142857074737549 
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7.11 CHAIN STATEMENT 
Syntax: 


CHAIN [MERGE ]<filespec>[,[<line number exp>] 
[ALL], DELETE <RANGE>]] 


See the examples below for illustration of the syntax options. 
Purpose: 

To call a program and pass variables to it from the current program. 
Remarks: 


<filespec> is a string expression containing a name that conforms to 
MS-DOS 2.0 rules for disk filenames or GW-BASIC rules for device 
specifications. 


<line number exp> is a line number or an expression that evaluates toa 
line number in the called program. It is the starting point for execution of 
the called program. If it is omitted, execution begins at the first line. <line 
number exp> is not affected by a RENUM command. 


With the ALL option, every variable in the current program 1s passed to 
the called program. If the ALL option is omitted, the current program 
must containa COMMON statement to list the variables that are passed. 
See Section 7.21 for information about COMMON. 


If the ALL option is used and <line number exp> is not, acomma must 
hold the place of <line number exp>. For example, CHAIN “NEXT- 
PROG”,ALL is correct; CHAIN “NEXTPROG”, ALL is incorrect. In the 
latter case, GW-BASIC assumes that ALL is a variable name and evalu- 
ates it as a line number expression. 


The MERGE option allows a subroutine to be brought into the GW- 
BASIC program as an overlay. That is, the current program and the called 
program are merged (see MERGE Command, Section 7.86). The called 
program must be an ASCII file if it is to be merged. 


After an overlay is used, it is usually desirable to delete it so that a new 
overlay may be brought in. To do this, use the DELETE option. 


The line numbers in <range> are affected by the RENUM command. 
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Examples: 


CHAIN is used in different ways in the two examples below. In the first, 
the two string arrays are dimensioned, and declared as common variables. 
When the program gets to line 90, it chains to the other program, which 
loads the B$s. At line 90 of PROG2, control chains back to the first 
program, but line 100s delineated, and so the first program executes from 
that line. This process can be observed through the descriptive text that 
prints as the programs execute. 


Example 1: 


10 REM THIS PROGRAM DEMONSTRATES CHAINING 
USING COMMON TO PASS VARIABLES 

20 REM SAVE THIS MODULE ON DISK AS “PROG1” 
USING THE A OPTION. 

30 DIM AS$(2),B3$(2) 

40 COMMON AS ),BS() 

50 A$(1)=“VARIABLES IN COMMON MUST BE ASSIGNED” 

60 A$(2)=“VALUES BEFORE CHAINING.” 

70 BS(1)=”” 

80 B$(2) =”” 

90 CHAIN “PROG2” 

100 PRINT 

110 PRINT BS$(1) 

120 PRINT 

130 PRINT BS(2) 

140 PRINT 

150 END 


10 REM THE STATEMENT “DIM AS(2),B$(2)” 
MAY ONLY BE EXECUTED ONCE 
20 REM HENCE, IT DOES NOT APPEAR IN THIS MODULE 
30 REM SAVE THIS MODULE ON THE DISK AS “PROG2” 
USING THE A OPTION 
40 COMMON AS ),B3( ) 
50 PRINT 
60 PRINT A$(1);A$(2) 
70 B$(1)=“NOTE HOW THE OPTION OF SPECIFYING 
A STARTING LINE NUMBER” 
80 B$(2)=“WHEN CHAINING AVOIDS THE DIMENSION 
STATEMENT IN ’PROG!’.” 
90 CHAIN “PROG1”,100 
100 END 
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In the second example, the MERGE, ALL, and DELETE options are 
illustrated. After A$ is loaded in the first program, control chains to line 
1010 of the second. At the second program’s line 1040, it chains to line 1010 
of the third program, keeping all variables and deleting all the second 
program’s lines. Control passes to the third program. This process can be 
observed through the descriptive text that prints as the programs execute. 


Example 2: 


10 REM THIS PROGRAM DEMONSTRATES CHAINING 
USING THE MERGE, ALL, AND DELETE OPTIONS. 

20 REM SAVE THIS MODULE ON THE DISK AS “MAINPRG”. 

30 A$=“MAINPRG” 

40 CHAIN MERGE “OVRLAY1”,1010, ALL 

50 END 


1000 REM SAVE THIS MODULE ON THE DISK AS 
“OVRLAY1” USING THE A OPTION. 

1010 PRINT A$; “ HAS CHAINED TO OVRLAYI1.” 

1020 A$=“OVRLAY 1” 

1030 B$=“OVRLAY2” 

1040 CHAIN MERGE “OVRLAY2”,1010,ALL, 
DELETE 1000-1050 

1050 END 


1000 REM SAVE THIS MODULE ON THE DISK AS 
“OVRLAY2” USING THE A OPTION. 

1010 PRINT A$; “ HAS CHAINED TO ”;B$:”.” 

1020 END 
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NOTE 


The CHAIN statement with MERGE 
option leaves the files open and pre- 
serves the current OPTION BASE 
setting. 


If the MERGE option is omitted, 
CHAIN does not preserve variable 
types or user-defined functions for 
use by the chained program. That 1s, 
any DEFINT, DEFSNG, DEFDBL, 
DEFSTR, or DEFFN statements con- 
taining snared variables must be re- 
stated in the chained program. 


When using the MERGE option, user- 
defined functions should be placed 
before any CHAIN MERGE state- 
ments in the program. Otherwise, the 
user-defined functions will be unde- 
fined after the merge is complete. 
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7.12 CHDIR STATEMENT 
Syntax: 

CHDIR PATHNAME cai 
Purpose: 
To change the current operating directory. 
Remarks: 
PATHNAME isastring specifying the name of the directory which is to be 
the current directory. CHDIR works exactly like the MS-DOS command 
CHDIR. The PATHNAME must be a string of less than 128 characters. 
Example: 

CHDIR “SALES” 
This makes SALES the current directory. e- 


CHDIR “B:USERS” 


This changes the current directory to USERS on drive B. It does NOT, 
however, change the default drive to B:. 


Also see the MK DIR and RMDIR statements. 
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7.13 CHR$ FUNCTION 
Syntax: 

CHRS&§(1) 
Purpose: 


To return a string whose one character is ASCII character I. (ASCII codes 
are listed in Appendix A.) 


Remarks: 


CHR$ is commonly used to send a special character to the screen or 
printer. For instance, the BELL character (CHRS$(7)) could be sent as a 
preface to an error message, or a form feed (CHR$(12)) could be sent to 
clear a terminal screen and return the cursor to the home position. 


Example: 


PRINT CHR$(66) 
will yield 
B 


See the ASC function, Section 7.2, for details on ASCII-to-numeric 
conversion. 
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7.14 CINT FUNCTION 
Syntax: 

CINT(X) a 
Purpose: 
To convert X to an integer by rounding the fractional portion. 
Remarks: 
If X is not in the range -32768 to 32767, an “Overflow” error occurs. 
Example: 


PRINT CINT(45.67) 
will yield 
46 
See the CDBL and CSNG functions for details on converting numbers to wd 


the double precision and single precision data type, respectively. See also 
the FIX and INT functions, both of which return integers. 
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7.15 CIRCLE STATEMENT 
Syntax: 


CIRCLE [STEP](<xcenter>,<ycenter>),<radius> 
[,<color> [,<start>,<end> [,<aspect>]]] 


The [STEP] option makes the specified center and ycenter coordinates 
relative to the “most recent point,” instead of absolute, mapped coordinates. 


<xcenter> is the x coordinate for the center of the circle. 
<ycenter> is the y coordinate for the center of the circle. 


<radius> is the radius of the circle in the current logical coordinate 
system. 


<color> is the numeric symbol for the color desired (see COLOR State- 
ment, Section 7.20). The default color is the foreground color. 


<start> and <end> are the start and end angles in radians. The range is 
-2 * pi through 2 * pi. These angles allow the user to specify where an ellipse 
will begin and end. If the start or end angle is negative, the ellipse will be 
connected to the center point with a line, and the angles will be treated as if 
they were positive. Note that this is different from adding 2 * pi. The start 
angle may be less than the end angle. 


<aspect> is the aspect ratio, i.e., the ratio of the x radius to the y radius. 
Default ratios depend on the machine that is being used. When default 
ratios are specified for the corresponding screen mode, a round circle is 
drawn. 


If the aspect ratio is less than one, the radius given is the x radius. If it is 
greater than one, the y radius is given. 


Purpose: 


To draw an ellipse or circle with the specified center and radius. 
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Remarks: 
The last point referenced after a circle is drawn is the center of the circle. 


It is not an error to supply coordinates that are outside the screen or — 
viewport. 


Coordinates can be shown as absolutes, as in the syntax shown above, or 
the STEP option can be used to reference a point relative to the most 
recent point used. The syntax of the STEP option 1s: 


STEP (<xoffset> <yoffset>) 


For example, if the most recent point referenced were (10,10), STEP (10,5) 
would reference a point offset 10 from the current x coordinate and offset 5 
from the current y coordinate, that is, the point (20,15). 


Example: 


Assume that the last point plotted was 100,50. Then, 


ai! 


CIRCLE (200,200),50 
and 
CIRCLE STEP (100,150),50 


will both draw a circle at 200,200 with radius 50. The first example uses 
absolute notation; the second uses relative notation. 
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7.16 CLEAR STATEMENT 
Syntax: 

CLEAR [,[<expression1>][,<expression2>]] 
Purpose: 


To set all numeric variables to zero, all string variables to null, and to close 
all open files; and, optionally, to set the end of memory and the amount of 
stack space. 


Remarks: 


<expressionI> is a memory location that, if specified, sets the highest 
location available for use by Microsoft GW-BASIC. 


<expression2> sets aside stack space for Microsoft GW-BASIC. The 
default is 768 bytes or one-eighth of the available memory, whichever is 
smaller. 


NOTE 


The CLEAR statement performs the 
following actions: 


Closes all files. 
Clears all COMMON variables. 


Resets numeric variables and arrays 
to zero. 


Resets the stack and string space. 


Resets all string variables and arrays 
to null. 


Releases all disk buffers. 


Resets all DEF FN and DEF 
SNG/DBL/STR statements. 


Examples: 


CLEAR 
CLEAR ,32768 
CLEAR ,,2000 
CLEAR ,32768,2000 
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7.17 CLOSE STATEMENT 
Syntax: . 

CLOSE [[#] <file number> [,[#] <file number...>]] 
Purpose: 


To conclude I/O toa file. The CLOSE statement is complementary to the 
OPEN statement. 


Remarks: 


<file number> is the number under which the file was opened. ACLOSE 
with no arguments closes all open files. 


The association of a particular file and a file number terminates upon 
execution of a CLOSE statement. The file may then be reopened using the 
same or a different file number. Once a file is closed, that file’s number may 
be used for any unopened file. 


A CLOSE for a sequential output file writes the final buffer of output. 


The SYSTEM, CLEAR, and END statements and the NEW and RESET 
commands always close all files automatically. 


Example: 


CLOSE #1,#2 
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7.18 CLS STATEMENT 
Syntax: 
CLS [n] 
Purpose: 
Erase contents of entire current screen. 
Remarks: 


n is the numeric expression in the range 0 to 2. 


ie TEXT MODE GRAPHICS MODE 


Clear the entire screen Clear graphics viewport only 









Clear the entire screen Clear the entire screen 








Not act Clear graphics viewport only 






Clear the entire screen 





Clear the entire screen 
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7.19 COLOR STATEMENT 

Purpose: 

Sets the colors for the foreground and background screen. The syntax of 
the COLOR statement depends on whether you are in the text mode or 
graphics mode, as set by the SCREEN statement. 


In text mode, you can set the following: 


Foreground — | of 8 colors 


Border — | of 8 colors 
In graphics mode, you can set the following: 


Background — | of 8 colors 
Palette — | of 3 palettes 


COLOR statement in Text mode: 
Syntax: 
COLOR [<foreground>],,<border>] 


<foreground> is a numeric expression in the range 0 to 31 representing 
the character color. 


<border> is anumeric expression in the range Oto 7. It is the color for the 
border screen. 


Remarks: 


When the screen mode (see “SCREEN Statement”) is color, the following 
colors are allowed for <foreground>: 


( — Black 

1 — Blue 

2 — Green 

3 — Cyan 

4 — Red 

5 — Magenta 
6 — Yellow 

7 — White 
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You can make characters blink by setting <foreground> equal to 16 plus 
the number of the desired color. That is, value of 16 to 31 causes blinking 
characters. 


You may select only colors 0 through 7 for <border>. 


When the screen mode (see “SCREEN Statement”) is Black and White, 
the following values can be used for <foreground>: 


0 — Blank 

1 — Under Line 
2 — Blink 

3 — Over Line 


4 — Reverse 

5 — Reverse 

6 — Reverse blink 

7 — Normal 
COLOR statement in Graphics mode: 
Syntax: 

COLOR [<background>],<palette>] 
<background> is a numeric expression specifying the background color. 
The colors allowed for <background> are 0 through 7, as described 
previously under “The COLOR Statement in Text Mode.” 


<palette> is a numeric expression which selects the palette of colors. 
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The colors selected when you choose each palette are as follows: 
COLOR PALETTE 0 PALETTE 1 PALETTE 2 
Green Cyan Blue — 


Red Magenta Green 


Yellow White Cyan 


Red 
Magenta 
Yellow 


White 





Any parameter may be omitted from the COLOR statement. Omitted 
parameters assume the old value. 


In graphics mode, the COLOR statement sets a background color and a 
palette of three or seven colors. You may select any one of these four or 
eight colors for display with the PSET, PRESET, LINE, CIRCLE, 
PAINT, and DRAW statements. 


Any values entered outside the range 0 to 255 will result in an “Illegal 
function call” error. Previous values will be retained. 


Example: 


5 SCREEN | 
10 COLOR 1,0 


Sets the background to blue, and selects palette 0. 


20 COLOR  , 1 
The background stays blue, and palette | is selected. 
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7.20 COM STATEMENT 
Syntax: 


COM(1) ON 
COM(1) OFF 
COM(1) STOP 


Purpose: 


To enable or disable event trapping of communications activity on the 
port. 


Remarks: 


The COM(1) ON statement enables communications event trapping by an 
ON COM statement (see ON COM Statement, Section 7.94). While 
trapping is enabled, and if a non-zero line number is specified in the ON 
COM statement, GW-BASIC checks between every statement to see if 
activity has occurred on the communications channel. If it has, the ON 
COM statement is executed. 


COM(1) OFF disables communications event trapping. If an event takes 
place, it is not remembered. 


COM(1) STOP disables communications event trapping, but if an event 
occurs, it is remembered. If there is a subsequent COM(1) ON statement, 
the remembered event will be successfully trapped. 


NOTE 
For additional information on com- 
munications event trapping, see “Event 
Trapping,” Section 6.2, and ON COM 
Statement, Section 7.94. 
Example: 
10 COM(1) ON 


Enables event trapping of communications activity. 
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7.21 COMMON STATEMENT 
Syntax: 

COMMON <list of variables> 
Purpose: 
To pass variables to a chained program. 
Remarks: 


The COMMON statement is used in conjunction with the CHAIN state- 
ment. COMMON statements may appear anywhere in a program, though 
it is recommended that they appear at the beginning. The same variable 
cannot appear in more than one COMMON statement. Array variables 
are specified by appending “( )” to the variable name. If all variables are to 
be passed, use CHAIN with the ALL option and omit the COMMON 
statement. 


Some Microsoft products allow the number of dimensions in the array to 
be included in the COMMON statement. GW-BASIC will accept that 
syntax, but will ignore the numeric expression itself. For example, the 
following statements are both valid and are considered equivalent: 


COMMON ( ) 
COMMON A(3) 


The number in parentheses is the number of dimensions, not the dimen- 
sions themselves. For example, the variable A(3) in this example might 
correspond to a DIM statement of DIM A(5,8,4). 

Example: 


100 COMMON A,B,C,D(),G$ 
110 CHAIN “PROG3”,10 
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7.22 CONT COMMAND 
Syntax: 

CONT 
Purpose: 


To continue program execution after a Break has been typed or a STOP 
statement has been executed. 


Remarks: 

Execution resumes at the point where the break occurred. If the break 
occurred after a prompt from an INPUT statement, execution continues 
with the reprinting of the prompt (“?” or prompt string). 

CONT is usually used in conjunction with STOP for debugging. When 
execution is stopped, intermediate values may be examined and changed 
using direct mode statements. Execution may be resumed with CONT ora 
direct mode GOTO, which resumes execution at a specified line number. 
CONT may be used to continue execution after an error has occurred. 
CONT is invalid if the program has been edited during the break. 
Example: 


See STOP Statement, Section 7.148.. 
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7.23 COS FUNCTION 
Syntax: 

COS(X) 
Purpose: 
To return the cosine of X, where X is in radians. 
Remarks: 
The calculation of COS(X) is performed in single precision, unless the / D 
switch is specified when BASIC is invoked and either the argument that 
receives the value of the cosine is a double precision variable or (X) 1s 
specified a double precision number with the # sign. 


Example: 


10 X=2*COS(.4) 
20 PRINT X 
will yield 
1.842122 
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7.24 CSNG FUNCTION 


Syntax: 
— CSNG(X) 
Purpose: 


To convert X to a single precision number. 


Example: 
10 A# = 975.3421115# 
20 PRINT A#, CSNG(A#) 
will yield 
975.3421115 975.3421 


See the CINT and CDBL functions for converting numbers to the integer 
and double precision data types, respectively. 
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7.25 CSRLIN FUNCTION 
Syntax: 
CSRLIN 
CSRLIN returns the current line position. 
Purpose: 
To obtain the current line position of the cursor in a numeric variable. 
Remarks: 


To return the current column position, use the POS function (Section 
7.117). 


Example: 


10 y= CSRLIN ’Record current line. 

20 x = POS(0) ’Record current column. 

30 LOCATE 24,1 

40 PRINT “HELLO” 

50 LOCATE x,y ’Restore position to old line and column | 
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7.26 CVI, CVS, CVD FUNCTIONS 
Syntax: 
CVI(<2-byte string>) 
CVS (<4-byte string>) 
CVD(<8-byte string>) 
Purpose: 
To convert string values to numeric values. 
Remarks: 
Numeric values that are read in from a random disk file must be converted 
from strings back into numbers. CVI converts a 2-byte string to an integer. 
CVS converts a 4-byte string to a single precision number. CVD converts 


an 8-byte string to a double precision number. 


Example: 


70 FIELD #1,4 AS NS, 12 AS BS. ... 
80 GET #1 
90 Y=CVS(N$) 


See also MKI$, MKS$, MK D§ Functions, Section 7.90. 
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7.27 DATA STATEMENT 
Syntax: 

DATA <list of constants> 
Purpose: 


To store the numeric and string constants that are accessed by the pro- 
gram’s READ statement(s). (See READ Statement, Section 7.126.) 


Remarks: 


DATA statements are nonexecutable and may be placed anywhere in the 
program. A DATA statement may contain as many constants as will fit on 
a line (separated by commas). Any number of DATA statements may be 
used in a program. READ statements access DATA statements in order 
(by line number). The data contained therein may be thought of as one 
continuous list of items, regardless of how many items are on a line or 
where the lines are placed in the program. 


<list of constants> may contain numeric constants in any format; 1.e., 
fixed-point, floating-point, or integer. (No numeric expressions are 
allowed in the list.) String constants in DATA statements must be sur- 
rounded by double quotation marks only if they contain commas, colons, 
or significant leading or trailing spaces. Otherwise, quotation marks are 
not needed. 


The variable type (numeric or string) given in the READ statement must 
agree with the corresponding constant in the DATA statement. 


DATA statements may be reread from the beginning by use of the RE- 
STORE statement (Section 7.130). 


Example: 


See READ Statement, Section 7.126. 
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7.28 DATES STATEMENT 

Syntax: 
DATE$=<string expression> 

<string expression> must be a string in one of the following forms: 
mm_-dd-yy 
mm-dd-yyyy 


mm/dd/yy 
mm/dd/yyyy 


Purpose: 


To set the current date. This statement complements the DATE$ function, 
which retrieves the current date. 


Remarks: 

The year must be in the range 1980 to 2099. If you use only one digit for the 
month or day, a 0 (zero) is assumed in front of it. If you give only one digit 
. for the year, a zero is appended to make it two digits. If you give only two 
digits for the year, if that is in the range 80 to 99, the year is assumed to be 
10yy, else 20yy. 

Example: 

10 DATE$=“07-01-1983” 


The current date is set at July 1, 1983. 
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7.29 DATES FUNCTION 
Syntax: 

DATE$ 
Purpose: 


To retrieve the current date. (To set the date, use the DATES statement, 
described in Section 7.28.) 


Remarks: 
The DATES function returns a ten-character string in the form mm-dd- 


yyyy, where mm 1s the month (01 through 12), dd is the day (01 through 
31), and yyyy is the year (1980 through 2099). 


Example: 
10 PRINT DATE$ 


The DATE$ function prints the date, calculated from the date set with the 
DATES$ statement. 
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7.30 DEF FN STATEMENT 
Syntax: 

DEF FN <name>[(<parameter list>)]=<function definition> 
Purpose: 
To define and name a function that is written by the user. 
Remarks: 


<name> must be a legal variable name. This name, preceded by FN, 
becomes the name of the function. 


<parameter list> consists of those variable names in the function defini- 
tion that are to be replaced when the function is called. The items in the list 
are separated by commas. 


<function definition> is an expression that performs the operation of the 
function. It is limited to one logical line. Variable names that appear in this 
expression serve only to define the function; they do not affect program 
variables that have the same name. A variable name used in a function 
definition may or may not appear in the parameter list. If it does, the value 
of the parameter is supplied when the function is called. Otherwise, the 
current value of the variable is used. 


The variables in the parameter list represent, on a one-to-one basis, the 
argument variables or values that will be given in the function call. 


This statement may define either numeric or string functions. If a type is 
specified in the function name, the value of the expression is forced to that 
type before it is returned to the calling statement. If a type is specified in the 
function name and the argument type does not match, a “Type mismatch” 
error occurs. 
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A DEF FN statement must be encountered before the function it defines 
may be called. If a function is called before it has been defined, an 
“Undefined user function” error occurs. DEF FN is illegal in the direct 
mode. 


Example: 


410 DEF FNAB(X,Y)=X “ 3/Y * 2 
420 T=FNAB(I,J) 


Line 410 defines the function FNAB. The function is called in line 420. 
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7.31 DEFINT/SNG/DBL/STR STATEMENTS 
Syntax: 

DEF <type> <range(s) of letters> 
where <type> is INT, SNG, DBL, or STR. 
Purpose: 


To declare variable types as integer, single precision, double precision, or 
string. 


Remarks: 

Any variable names beginning with the letter(s) specified in <range of 
letters> will be considered the type of variable specified in the <type> 
portion of the statement. However, a type declaration character always 
takes precedence over a DEFtype statement. (See “Variable Names and 
Declaration Characters,” Section 3.3.1.) 

If no type declaration statements are encountered, GW-BASIC assumes 
that all variables without declaration characters are single precision 
variables. 

Examples: 


10 DEFDBL L-P 


All variables beginning with the letters L, M, N, O, and P will be double 
precision variables. 


10 DEFSTR A 
All variables beginning with the letter A will be string variables. 
10 DEFINT I-N,W-Z 


All variables beginning with the letters I, J, K, L, M, N, W, X, Y, Z will be 
integer variables. 
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7.32 DEF SEG STATEMENT 
Syntax: 
DEF SEG [=<address>] 


where <address> is a numeric expression returning an unsigned integer 
in the range 0 to 65535. 


Purpose: 


To assign the current segment address to be referenced by a subsequent 
BLOAD, BSAVE, CALL, CALLS, or POKE statement or by a USR or 
PEEK function. 


Remarks: 


The address specified is saved for use as the segment required by BLOAD, 
BSAVE, CALL, CALLS, POKE, USR, and PEEK. 


Entry of any value outside the <address> range 0 through 65535 will 
result in an “Illegal function call” error, and the previous value will be 
retained. 


If the <address> option is omitted, the segment to be used is set to the 
GW-BASIC data segment. This is the initial default value. 


NOTE 


DEF and SEG must be separated bya 
space. Otherwise, GW-BASIC will 
interpret the statement DEFSEG=100 
to mean “assign the value 100 to the 
variable DEFSEG.” 


Example: 


10 DEF SEG=&HB800 ’Seg segment at B800 Hex 
20 DEF SEG ’Restore segment to GW-BASIC data segment 
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7.33 DEF USR STATEMENT 
Syntax: 

DEF USR[<digit>]=<integer expression> 
Purpose: 
To specify the starting address of an assembly language subroutine. 
Remarks: 
<digit> may be any digit from 0 to 9. The digit corresponds to the number 
of the USR routine whose address is ‘being specified. If <digit> is 
omitted, DEF USRO is assumed. The value of <integer expression> is the 
starting address of the USR routine. 
Any number of DEF USR statements may appear ina program to redefine 
subroutine starting addresses, thus allowing access to as many subroutines 


as necessary. 


Example: 


200 DEF USRO0=24000 
210 X=USRO(Y 4 2/2.89) 
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7.34 DELETE COMMAND 
Syntax: 
DELETE {[{<line number>][-<line number>][<line number>-]}} 
Purpose: 
To delete program lines. 
Remarks: 
Microsoft GW-BASIC always returns to command level aftera DELETE 
is executed. If <line number> does not exist, an “Illegal function call” 
error occurs. 
Examples: 
DELETE 40 
Deletes line 40. 
DELETE 40-100 
Deletes lines 40 through 100, inclusive. 
DELETE -40 
Deletes all lines up to and including line 40. 
DELETE 40- 
Deletes lines 40 through the end, inclusive. 
DELETE . 


Deletes current line. 
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7.35 DIM STATEMENT 
Syntax: 

DIM <list of subscripted variables> 
Purpose: 


To specify the maximum values for array variable subscripts and allocate 
storage accordingly. 


Remarks: 


If an array variable name is used without a DIM statement, the maximum 
value of the array’s subscript(s) is assumed to be 10. If a subscript is used 
that is greater than the maximum specified, a “Subscript out of range” 
error occurs. The minimum value for a subscript is 0, unless otherwise 
specified with the OPTION BASE statement (see Section 7.104). 


The DIM statement sets all the elements of the specified numerical arrays 
to an initial value of zero and elements of string arrays to null strings. 


Theoretically, the maximum number of dimensions allowed in a DIM 
statement is 255. In reality, however, that number would be impossible, 
since the name and punctuation are also counted as spaces on the line, and 
the line itself has a limit of 255 characters. 


If the default dimension (10) has already been established for an array 
variable, and that variable is later encountered in a DIM statement, an 
“Array already dimensioned” error results. Therefore, it is good pro- 
gramming practice to put the required DIM statements at the beginning of 
a program, outside of any processing loops. 


Example: 
10 DIM A(20) 
20 FOR I=0 TO 20 


30 READ A(J) 
40 NEXT I 
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7.36 DRAW STATEMENT 
Syntax: 
DRAW <string expression> 


where <string expression> is one of the subcommands described below 
in “Remarks.” 


Purpose: 

To draw an object defined by the subcommands described below. 
Remarks: 

The DRAW statement combines many of the capabilities of the other 
graphics statements into the Graphics Macro Language. The Graphics 
Macro Language defines a set of characteristics that comprehensively 
describe a particular image. In this case, the characteristics include motion 
(up, down, left, right), color, angle, and scale factor. 

Each of the following subcommands initiates movement from the current 
graphics position. This is usually the coordinate of the last graphics point 
plotted with another GML command. The current position defaults to the 
center of the screen when a program is run. 


Prefixes 


The following prefix commands may precede any of the movement 
commands: 


B Move but don’t plot any points. 


N Move but return to original position when done. 


Cursor Movement 
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The following commands specify movement in units. The size of a unit 
may be modified by the S command. The default unit size is one point. If 
no argument is supplied, the cursor is moved one unit. 


U [<n>] 
D [<n>] 
L [<n>] 
R [<n>] 
E [<n>] 
F [<n>] 
G [<n>] 
H [<n>] 


Move up (scale factor *n) points 
Move down 

Move left 

Move right 

Move diagonally up and right 
Move diagonally down and right 
Move diagonally down and left 
Move diagonally up and left 


Other Commands 


M <x,y> 


Move absolute or relative. If x is preceded by a plus (+) or minus (-), x 
and y are added to the current graphics position and connected with 
the current position by a line. Otherwise, a line is drawn to point x,y 
from the current cursor position. 


A <n> 


Set angle n. n may range from 0 to 3, where 0 is 0 degrees, | is 90, 2 is 
180, and 3 is 270. Figures rotated 90 or 270 degrees are scaled so they 
will appear the same size as with 0 or 180 degrees on a monitor screen 
with the standard aspect ratio of 4/3. 


TA <degrees> - rotate <degrees>. 


DEGREES must be in the range -360 to 360 degrees. If DEGREES 1s 
positive, rotation is counterclockwise. If DEGREES is negative, 
rotation is clockwise. 


Example: 


FOR D=0 TO 360 ’Draw spokes 
DRAW “TA=D;NU50 
NEXT D 
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C <n> 
Set color n. 


S <n> 


Set scale factor. n may range from | to 255. The scale factor multi- 
plied by the distances given with U, D, L, R, E, F, G, H and relative M 
commands gives the actual distance traveled. 


X <string expression> 


Execute substring. This powerful command allows you to execute a 
second substring from a string, much like GOSUB in Microsoft 
BASIC. You can have one string execute another, which executes a 
third, and so on. 


Numeric arguments can be constants like “123” or “=<variable>” 
where <variable> is the name of a variable. 


P <paintcolor>,<bordercolor>. 


<paintcolor> is an integer paint attribute, and <bordercolor> is 
the integer border attribute. “Tile” painting is not supported in Draw. 


Examples: 


DRAW “U50R50D50L50” "Draw a box 
DRAW “BE10” "Move up and right into box 
DRAW “P1,3” ’Paint interior 


10 U$=“U30;” 

20 D$=“U30;” 

30 L$="L40;” 

40 R$=“R40;” 

50 BOX$=U$+R$+D$+L$ 
60 DRAW “XBOX$;” 


The statement DRAW “XU$;XR$;XD$;XL$;” would have drawn the 
same box. 
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7.37 EDIT COMMAND 
Syntax: 
EDIT <dJine number> 
Purpose: 
To edit the specified line. 
Remarks: 
When EDIT is used, GW-BASIC types the specified program line and 
leaves the user in direct mode. The cursor is placed on the first character of 


the program line. 


See Chapter 4, “Writing Programs Using the GW-BASIC Editor,” for full 
details on screen editing capabilities. 
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7.38 END STATEMENT 
Syntax: 

END 
Purpose: 


To terminate program execution, close all files, and return to command 
level. 


Remarks: 

END statements may be placed anywhere in the program to terminate 
execution. Unlike the STOP statement, END does not cause a “Break in 
line nnnnn” message to be printed. An END statement at the end of a 
program is optional. Microsoft GW-BASIC always returns to command 
level after an END is executed. 


Example: 


520 IF K>1000 THEN END ELSE GOTO 20 
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7.39 ENVIRON STATEMENT 
Syntax: 
ENVIRON <string> 
Purpose: 
To modify a parameter in MS-DOS’s Environment String Table. 
Remarks: 


<string> is a string expression. The value of the expression must be of the 
form <parameter-id> = <text>, or <parameter-id> <text>. Every- 
thing to the left of the equal sign or space will be assumed to be a 
parameter, and everything to the right, text. 


If the parameter-id has not previously existed in the Environment String 
Table, it will be appended to the end of the table. If the parameter-id exists 
on the table when the ENVIRON statement is executed, the existing 
parameter-id is deleted and the new one appended to the end of the table. 


66 99 


The text string is the new parameter text. If the text is a null string (“”), or 
consists only of a semicolon (“;”) then the existing parameter-id will be 
removed from the Environment String Table, and the remaining body of 


the file compressed. 


This statement could be used to change the “PATH” parameter for a child 
process, or to pass parameters to a child by inventing a new Environment 
Parameter. (See the MS-DOS 2.0 Utilities — PATH Command.) 


Errors include parameters that are not strings and an “out of memory” 


when no more space can be allocated to the Environment String Table. 
The amount of free space in the table will usually be quite small. 
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Example: 


The following MS-DOS command will create a default “PATH” to the 
root directory on DISK A: 


PATH=A: 

The PATH may be changed to a new value by: 
ENVIRON “PATH=A:sALES;A:aCCOUNTING” 

A new parameter may be added to the Environment String Table: 
ENVIRON “SESAME=PLAN” 

The Environment String Table now contains: 


PATH=A:sALES;A:aCCOUNTING 
SESAME=PLAN 


If you then entered: 
ENVIRON “SESAME:;-;” 


then you would have deleted SESAME, and you would have a table 
containing: 


PATH=A:sALES;A:aCCOUNTING 


Also see ENVIRONS$ Function and SHELL Command, Sections 7.40 and 
7.141, respectively. 
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7.40 ENVIRONS FUNCTION 
Syntax: 


ENVIRONS (<string parameter>) 
ENVIRONS$ (<n>) 


where n is an integer. 

Purpose: 

To retrieve a parameter string from BASIC’s Environment String Table. 
Remarks: 


The string result returned by the ENVIRON$ function may not exceed 255 
characters. If a parameter name is specified, and if it either cannot be 
found or it has no text following it, a null string is returned by 
ENVIRONS. When the parameter name is specified, ENVIRON$ returns 
all the associated text that follows “<parameter>=” in the Environment 
String Table. 


If the argument is numeric, the nth string in the Environment String Table 
is returned. It includes all the text, including the parameter name. If the 
nth string does not exist, a null string is returned. 
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7.41 EOF FUNCTION 

Syntax: 
EOF(<file number>) e 

Purpose: 

To test for the end-of-file condition. 

Remarks: 


Returns -1 (true) if the end of a sequential file has been reached. Use EOF 
to test for end-of-file while inputting, to avoid “Input past end” errors. 


When EOF is used with random access files, it returns “true” if the last 
executed GET statement was unable to read an entire record because of an 
attempt to read beyond the end. 


When EOF is used with a communications device, the definition of the 

end-of-file condition is dependent on the mode (ASCII or binary) that the > 
device was opened in. In binary mode, EOF is true when the input queue is 
empty (LOC(n)=0). It becomes false when the input queue is not empty. In 

ASCII mode, EOF is false until a Control-Z is received, and from then on 

it will remain true until the device is closed. 


Example: 


10 OPEN “I”, 1,“DATA” 
20 C=0 

30 IF EOF(1) THEN 100 
40 INPUT #1,M(C) 

50 C=C+1:GOTO 30 
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7.42 ERASE STATEMENT 
Syntax: 
ERASE <list of array variables> 
Purpose: 
To eliminate arrays from memory. 
Remarks: 
Arrays may be redimensioned after they are erased, or the previously 
allocated array space in memory may be used for other purposes. If an 
attempt is made to redimension an array without first erasing it, a “Dupli- 


cate definition” error occurs. 


Example: 


450 ERASE A.B 
460 DIM B(99) 
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7.43 ERDEV,ERDEV$ FUNCTIONS 
Syntax: 

ERDEV ERDEV$ 
Purpose: 
To provide a way to obtain device-specific status information. ERDEV is 
an integer function which contains the error code returned by the last 
device to declare an error. ERDEV$is a string function which contains the 
name of the Device Driver which generated the error. 
Remarks: 


These functions may not be set by the programmer. 


ERDEV is set by the Interrupt X’24’ handler when an error within DOS is 
detected. 


ERDEV will contain the INT 24 error code in the lower eight bits. 
Example: 


If a user-installed Device Driver, “MYLPT2”, ran out of paper, and the 
Driver’s error number for that problem was “9”: 


PRINT ERDEV, ERDEV$ 
will yield 
9 MYLPT2 
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7.44 ERR AND ERL FUNCTIONS 
Syntax: 

ERR ERL 
Remarks: 


When anerror handling routine is entered, the function ERR contains the 
error code for the error and the function ERL contains the line number of 
the line in which the error was detected. The ERR and ERL functions are 
usually used in IF... THEN statements to direct program flow in the error 
handling routine. 


With the GW-BASIC Interpreter, if the statement that caused the error 
was a direct mode statement, ERL will contain 65535. 


If the line number is not on the right side of the relational operator, it 
cannot be renumbered with RENUM. Because ERL and ERR are 
reserved words, neither may appear to the left of the equal sign ina LET 
(assignment) statement. Microsoft GW-BASIC error codes are listed in 
Appendix B. 

Example: 


To test whether an error occurred in a direct statement, the user could 
enter: 


IF 65535 = ERL THEN PRINT “Direct Error” 
When testing within a program, use: 


IF ERR-=error code THEN ... 
IF ERL=line number THEN ... 
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7.45 ERROR STATEMENT 
Syntax: 

ERROR <integer expression> 
Purpose: 


To simulate the occurrence of a BASIC error, or to allow error codes to be 
defined by the user. 


Remarks: 


ERROR can be used as a statement (part of a program source line) or asa 
command (in direct mode). 


The value of <integer expression> must be greater than 0 and less than 
256. If the value of <integer expression> equals an error code already in 
use by BASIC (see Appendix B), the ERROR statement will simulate the 
occurrence of that error and the corresponding error message will be 
printed. (See Example 1.) 


To define your own error code, use a value that is greater than any used by 
Microsoft GW-BASIC error codes. (It is preferable to use the highest 
available values, so compatibility may be maintained when more error 
codes are added to Microsoft GW-BASIC.) This user-defined error code 
may then be conveniently handled in an error handling routine. (See 
Example 2.) 


If an ERROR statement specifies a code for which no error message has 
been defined, Microsoft GW-BASIC responds with the “Unprintable 
error” error message. Execution of an ERROR statement for which there 
is no error handling routine causes an error message to be printed and 
execution to halt. 
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Example 1: 


20 $=15 
30 ERROR S 
40 END 


will yield 
String too long in line 30 


Or, in direct mode (interpreter only): 


Ok 
ERROR 15 (You type this line.) 
String too long (GW-BASIC types this line.) 
Ok 
Example 2: 


110 ON ERROR GOTO 400 
120 INPUT “WHAT IS YOUR BET”:B 
130 IF B>5000 THEN ERROR 210 


400 IF ERR=210 THEN PRINT “HOUSE LIMIT IS $5000” 
410 IF ERL=130 THEN RESUME 120 
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7.46 EXP FUNCTION 
Syntax: 

EXP(X) . 
Purpose: 


To return e (base of natural logarithms) to the power of X. X must be <= 
88.02969. 


Remarks: 


If x is greater than 88.02969, the “Overflow” error message is displayed, 
machine infinity with the appropriate sign is supplied as the result, and 
execution continues. 


The EXP function will return a single precision value unless the /D switch 
was used when BASIC was invoked and a double precision variable is used 
as the argument. 


Example: 


10 X=5 

20 PRINT EXP(X-1) 
will yield 

54.59815 
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7.47 FIELD STATEMENT 
Syntax: 
FIELD [#] <file number> , <field width> AS <string variable> ... 
Purpose: 
To allocate space for variables in a random file buffer. 
Remarks: 


Before a GET statement or PUT statement can be executed, a FIELD 
statement must be executed to format the random file buffer. 


<file number> is the number under which the file was opened. <field 


-width> is the number of characters to be allocated to <string variable>. 


The total number of bytes allocated in a FIELD statement must not 
exceed the record length that was specified when the file was opened. 
Otherwise, a “Field overflow” error occurs. (The default record length 1s 
128 bytes.) 


Any number of FIELD statements may be executed for the same file. All 
FIELD statements that have been executed will remain in effect at the 
same time. 


Any field statement which is executed while a file is opened has no effect 
after that file is closed. For example, assume file | is opened, fielded, and 
closed. If file 1 is re-opened it should be re-fielded. 


NOTE 


Do not use a fielded variable name in 
an INPUT or LET statement. Once a 
variable name is fielded, it points to 
the correct place in the random file 
buffer. If a subsequent INPUT or 
LET statement with that variable 
name is executed, the variable no 
longer refers to the random file record 
buffer, but to the variables stored in 
string space. 
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Example 1: 
FIELD 1,20 AS N$,10 AS ID$,40 AS ADD$ 


Allocates the first 20 bytes in the random file buffer to the string variable 
N§, the next 10 bytes to ID$, and the next 40 to ADD$. FIELD does not 
place any data in the random file buffer. (See also GET Statement, Section 
7.52, and LSET and RSET Statements, Section 7.85.) 


Example 2: 


10 OPEN “R,”#1,“A:PHONELST”,35 

15 FIELD #1,2 AS RECNBR$,33 AS DUMMY$ 
20 FIELD #1,25 AS NAMES, 10 AS PHONENBR$ 
25 GET #1 

30 TOTAL=CVI(RECNBR)$ 

35 FOR I=2 TO TOTAL 

40 GET#I,I 

45 PRINT NAMES, PHONENBR$ 

50 NEXT I 


Illustrates a multiple defined FIELD statement. In statement 15, the 
35-byte field is defined for the first record to keep track of the number of 
records in the file. In the next loop of statements (35-50), statement 20 
defines the field for individual names and phone numbers. 


Example 3: 
10 FOR LOOP%=0 TO 7 
20 FIELD #1,(LOOP%*16) AS OFFSET$,16 AS A$(LOOP%) 
30 NEXT LOOP% 


Shows the construction of a FIELD statement using an array of elements 
of equal size. The result is equivalent to the single declaration: 


FIELD #1,16 AS A$(0),16 AS A$(1),...,16 AS A$(6),16 AS A$(7) 
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Example 4: 


10 DIM SIZE% (4%): REM ARRAY OF FIELD SIZES 
20 FOR LOOP%=0 TO 4% 

30 READ SIZE% (LOOP%) 

40 NEXT LOOP% 

50 DATA 9,10,11,12,21,41 


120 DIM A$(4%): REM ARRAY OF FIELDED VARIABLES 
130 OFFSET%=0 » 
140 FOR LOOP%=0 TO 4% 
150 FIELD #1,OFFSET% AS OFFSET$,SIZE%(LOOP%) 
AS A$(LOOP%) 
160 OFFSET%=OFFSET%+SIZE%(LOOP%) 
170 NEXT LOOP% | 


Creates a field in the same manner as Example 3. However, the element 
size varies with each element. The equivalent declaration is: 


FIELD #1,SIZE%(0) AS A$(0),SIZE%(1) AS A$(1).... 
SIZE%(4%) AS AS$(4%) 
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7.48 FILES STATEMENT 
Syntax: 
FILES [<filespec>] 


where <filespec> includes either a filename or a pathname and optional 
device designation. 


Purpose: 

To print the names of files residing on the specified disk. 

Remarks: 

If <filespec> is omitted, all the files on the currently selected drive will be 
listed. <filespec> is a string formula which may contain question marks 
(?) or asterisks (*) used as wild cards. A question mark will match any 
single character in the filename or extension. An asterisk will match one or 
more characters starting at that position. The asterisk is a shorthand 
notation for a series of question marks. The asterisk need not be used in the 


case where all the files on a drive are requested, e.g., FILES “B:”. 


If a filespec is used, and no explicit path is given, the current directory is 
the default. 


Examples: 
FILES 

Shows all files on the current directory. 
FILES “*.BAS” 

Shows all files with extension .BAS. 
FILES “B:*.*” 

Shows all files on drive B. 


FILES “B:” (equivalent to “B:*.*”) 
FILES “TEST?.BAS” 
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Shows all five-letter files whose names start with “TEST” and end with the 
.BAS extension. 


FILES “\SALES” 
If SALES is a subdirectory of the current directory, this statement displays 
SALES <dir>. If SALES is a file in the current directory, this statement 
displays SALES. 

FILES “\SALES\MARY” 


Displays MARY <dir> if MARY is a subdirectory of SALES or if 
MARY is a file, displays its name. 
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7.49 FIX FUNCTION 
Syntax: 
FIX(X) - 
Purpose: 
To return the truncated integer part of X. 
Remarks: 
FIX(X) is equivalent to SGN(X)*INT(ABS(X)). The difference between 
FIX and INT is that FIX does not return the next lower number for 
negative X. 


Examples: 


PRINT FIX(58.75) 
will yield > 
58 — 


PRINT FIX(-58.75) 
will yield 
-58 
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7.50 FOR...NEXT STATEMENT 
Syntax: 


FOR <variable>=x TO y [STEP z] 


NEXT [<variable>][,<variable>... | 
where x, y, and z are numeric expressions. 
Purpose: 


To allow a series of instructions to be performed ina loop a given number 
of times. 


Remarks: 


<variable> is used as a counter. The first numeric expression (x) is the 
initial value of the counter. The second numeric expression (y) is the final 
value of the counter. The program lines following the FOR statement are 
executed until the NEXT statement is encountered. Then the counter is 
adjusted by the amount specified by STEP. A check is performed to see if 
the value of the counter is now greater than the final value (y). If it is not 
greater, GW-BASIC branches back to the statement after the FOR state- 
ment and the process is repeated. If it is greater, execution continues with 
the statement following the NEXT statement. This isa FOR...NEXT loop. 


If STEP is not specified, the increment is assumed to be one. If STEP 1s 
negative, the final value of the counter is set to be less than the initial value. 
The counter is decreased each time through the loop. The loop is executed 
until the counter is less than the final value. 


The counter must be an integer or single precision numeric constant. If a 
double precision numeric constant is used, a “Type mismatch” error will 
result. 


The body of the loop is skipped if the initial value of the loop times the sign 
of the STEP exceeds the final value times the sign of the STEP. 
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Nested Loops 


FOR...NEXT loops may be nested; that is, a FOR...NEXT loop may be 
placed within the context of another FOR...NEXT loop. When loops are | 
nested, each loop must have a unique variable name as its counter. The wast 
NEXT statement for the inside loop must appear before that for the 
outside loop. If nested loops have the same end point, a single NEXT 
statement may be used for all of them. 


The variable(s) in the NEXT statement may be omitted, in which case the 
NEXT statement will match the most recent FOR statement. If a NEXT 
statement is encountered before its corresponding FOR statement, a 
“NEXT without FOR” error message Is issued and execution is terminated. 


Example 1: 
10 K=10 
20 FOR I= 1 TO 10 STEP 2 
30 =PRINT I; 
40 LET K =K+10 
50 PRINT K 
60 NEXT I 


will yield 
1 20 


In this example, the loop counter, I, advances +2 on each cycle. The loop 
prints the counter, increments K, and prints K. 
Example 2: 
10 J=0 20 FOR I=1 TO J 30 PRINT I 40 NEXT I 
In this example, the loop does not execute because the initial value of the 
loop exceeds the final value. 
Example 3: 
10 I=5 
20 FOR I=1 TO I+5 
30 =PRINT J; | 
40 NEXT I al 


will yield 


123 45 67 8 9 10 
In this example, the loop executes ten times. The final value for the loop 
variable is always set before the initial value is set. 
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7.51 FRE FUNCTION 
Syntax: 


FRE(0) 
FRE(“”) 


Purpose: 
With a numeric argument, FRE returns the number of bytes in memory 
that are not being used by Microsoft GW-BASIC. Arguments to FRE are 


dummy arguments. 


FRE(“”) forces a garbage collection before returning the number of free 
bytes. 


Remarks: 

GW-BASIC will not initiate garbage collection until all free memory has 
been used up. Therefore, using FRE(“”) periodically will result in shorter 
delays for each garbage collection. 


Example: 


PRINT FRE(0) 
might yield 
14542 
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7.52 GET STATEMENT — FILE I/O 
Syntax: 
GET [#]<file number>[,<record number>] 
Purpose: 
To read a record from a random disk file into a random buffer. 
Remarks: 


<file number> is the number under which the file was OPENed. If 
<record number> is omitted, the next record (after the last GET) is read 
into the buffer. The largest possible record number is 16,777,215. 


The GET and PUT statements allow fixed-length input and output for 
GW-BASIC COM files. However, because of the low performance asso- 
ciated with telephone line communications, we recommend that you do 
not use GET and PUT for telephone communication. 


Example: 
GET #1,75 


NOTE 


After a GET statement has been exe- 
cuted, INPUT# and LINE INPUT# 
may be executed to read characters 
from the random file buffer. The EOF 
function may be used after a GET 
statement to see if that GET was 
beyond the end of file marker. 
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7.53 GET STATEMENT — GRAPHICS 
Syntax: 

GET (xl,y1)-(x2,y2),<array name> 
used with 

PUT (xl,yl),<array name> [,action verb] 
where (xl,y1)-(x2,y2) is a rectangular area on the display screen. The 
rectangle is defined with (x1,yl) and (x2,y2) being the upper left and the 
lower right vertices. 
<array name> is the name assigned to the place that will hold the image. 
The array can be any type except string. It must be dimensioned large 
enough to hold the entire image, otherwise an “Illegal function call” 
results. Unless the array is type integer, the contents of the array after a 
GET will be meaningless when interpreted directly (see below). 


Purpose: 


The GET and PUT statements are used together to transfer graphic images 
to and from the screen. 


The GET statement transfers the screen image bounded by the rectangle 
described by the specified points into the array. 


The PUT statement transfers the image stored in the array onto the screen. 
Remarks: 

One of the most useful things that can be done with GET and PUT is 
animation. (See PUT Statement, Section 7.131, for discussion of anima- 
tion.) 

GET reads the colors of the points within the specified rectangle into the 
array. The specified rectangle has points (x/,y/) and (x2,y2) as opposite 


corners. (This is the same as the rectangle drawn by the LINE statement 
using the B option.) 
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GET and PUT can be used for high speed object motion in graphics mode. 
You might think of GET and PUT as ”bit pump” operations which move 
bits onto (PUT) and off of (GET) the screen Remember that PUT and 
GET are also used for random access files, but the syntax of these state- 
ments is different. 


The array is used simply as a place to hold the image and must be numeric; 
it may be any precision, however. The required size of the array, in bytes, is: 


4+INT((x*bitsperpixel+7)/8)*y 


where x and y are the lengths of the horizontal and vertical sides of the 
rectangle, respectively. The value of bitsperpixel is 3 in color mode, and | 
in b/w mode. 


For example, suppose we want to use the GET statement to get a 10 by 12 
image in color mode. The number of bytes required is 4+INT((10*3+ 
7)/8) *12, or 52 bytes. The bytes per element of an array are: 


@ 2 for integer 
@ 4 for single-precision 
@ 8 for double-precision 


Therefore, we could use an integer array with at least 26 elements. 
The information from the screen is stored in the array as follows: 


1. two bytes giving the x dimension in bits 
2. two bytes giving the y dimension in bits 
3. the data itself 


It is possible to examine the x and y dimensions and even the data itself if 
an integer array is used. The x dimension is in element 0 of the array, and 
the y dimension is in element |. Keep in mind, however, that integers are 
stored low byte first, then high byte; but the data is actually transferred 
high byte first, then low byte. 
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7.54 GOSUB...RETURN STATEMENTS 
Syntax: 


GOSUB <line number> 


RETURN [<line number>] 
Purpose: 
To branch to, and return from, a subroutine. 
Remarks: 
<line number> inthe GOSUB statement is the first line of the subroutine. 
A subroutine may be called any number of times in a program. A subrou- 
tine also may be called from within another subroutine. Such nesting of 
subroutines is limited only by available memory. 
Simple RETURN statement(s) in a subroutine cause Microsoft GW- 
BASIC to branch back to the statement following the most recent GOSUB 
statement. A subroutine may contain more than one RETURN statement. 
The <line number> option may be included in the RETURN statement 
to return to a specific line number from the subroutine. Use this type of 
return with care, however, because any other GOSUBs, WHILEs, or 


FORs that were active at the time of the GOS UB will remain active, and 
errors such as “FOR without NEXT” may result. 


7-71 


Basic Commands, Functions and Statements 


Subroutines may appear anywhere in the program, but it is recommended 
that the subroutine be readily distinguishable from the main program. To 
prevent inadvertent entry into the subroutine, precede it with a STOP, 
END, or GOTO statement that directs program control around the sub- on 
routine. wut 


Example: 


10 GOSUB 40 

20 PRINT “BACK FROM SUBROUTINE” 
30 END 

40 PRINT “SUBROUTINE”; 

50 PRINT “ IN”; 

60 PRINT “ PROGRESS” 

70 RETURN 


will yield 


SUBROUTINE IN PROGRESS 
BACK FROM SUBROUTINE 
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GOTO <line number> 


Purpose: 
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To branch unconditionally to a specified line number. 


Remarks: 


If <dine number> is an executable statement, that statement and those 
following are executed. If it is a nonexecutable statement, execution 


proceeds at the first executable statement encountered after 


number>. 
Example: 
10 READ R 


20 PRINT “R ="3R, 
30 A=3.14*R*2 


40 PRINT “AREA =”3;A 


<line 


50 GOTO 10 

60 DATA 5,7,12 

will yield 

R=5 AREA = 78.5 
R=7 AREA = 153.86 
R= 12 AREA = 452.16 


Out of DATA in 10 
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7.56 HEX$ FUNCTION 
Syntax: 

HEX$(X) 
Purpose: 


To return a string that represents the hexadecimal value of the decimal 
argument. 


Remarks: 
X is rounded to an integer before HEX$(X) is evaluated (-32768 ~ 65535). 
Example: 

10 INPUT X 


20 A$=HEX$(X) 
30 PRINT X “DECIMAL IS ” A$ “ HEXADECIMAL” 


will yield 
? 32 
32 DECIMAL IS 20 HEXADECIMAL 


See the OCT$ function, Section 7.93, for details on octal conversion. 
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7.57 IF... THEN[...ELSE]/IF...GOTO STATEMENTS 
Syntax: 


IF <expression>[,|THEN {<statement(s)>:<line number>} 
[ [ELSE {<statement(s)>:<line number>}]] 


Syntax: 


IF <expression>[,|GOTO <line number> 
[ [ELSE {<statement(s)>:<line number>}]] 


Purpose: 


To make a decision regarding program flow based on the result returned 
by an expression. 


Remarks: 


If the result of <expression> is not zero, the THEN or GOTO clause is 
executed. THEN may be followed by either a line number for branching or 
one or more statements to be executed. GOTO 1s always followed by a line 
number. If the result of <expression> is zero, the THEN or GOTO clause 
is ignored and the ELSE clause, if present, is executed. Execution con- 


tinues with the next executable statement. A comma is allowed before 
THEN. 


Nesting of IF Statements 


IF... THEN...ELSE statements may be nested. Nesting is limited only by 
the length of the line. For example, 


IF X>Y THEN PRINT “GREATER” ELSE IF X>Y 
THEN PRINT “LESS THAN” ELSE PRINT “EQUAL” 


is a legal statement. If the statement does not contain the same number of 
ELSE and THEN clauses, each ELSE is matched with the closest 
unmatched THEN. For example, 


IF A=B THEN IF B=C THEN PRINT “A=C” 
ELSE PRINT “A<>C” 


will not print “A<>C” when A<>B. 
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If an IF... THEN statement is followed by a line number in direct mode, an 
“Undefined line” error results, unless a statement with the specified line 
number had previously been entered in indirect mode. 


NOTE 


When using IF to test equality for a 
value that is the result of a floating- 
point computation, remember that 
the internal representation of the 
value may not be exact. Therefore, 
the test should be against the range 
over which the accuracy of the value 
may vary. For example, to test a 
computed variable A against the value 
1.0, use: 


IF ABS (A-1.0)<1.0E-6 THEN ... 
This test returns true if the value of A 


is 1.0 with a relative error of less than 
1.0E-6. 
Example 1: 
200 IF I THEN GET#1,I 


This statement GETs record number | if I is not zero. 
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Example 2: 


100 IF(I<20)*(I>10) THEN DB=1979-1:GOTO 300 
110 PRINT “OUT OF RANGE” 


In this example, a test determines if I is greater than 10 and less than 20. If I 
is in this range, DB is calculated and execution branches to line 300. If I 1s 
not in this range, execution continues with line 110. 
Example 3: 

210 IF IOFLAG THEN PRINT A$ ELSE LPRINT A$ 
This statement causes printed output to go either to the screen or the line 


printer, depending on the value of the variable IOFLAG. If IOFLAG is 
zero, output goes to the line printer; otherwise, output goes to the screen. 
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7.58 INKEYS FUNCTION 
Syntax: 

INKEYS 
Purpose: 


Reads a character from the keyboard containing a character read from the 
standard input device or a null string if no character is pending there. The 
keyboard is usually the standard input device. 


Remarks: 


INKEYS only reads a single character, even if there are several characters 
waiting in the keyboard buffer. The returned value is a zero-, one-, or 
two-character string. 


@ A null string (length zero) indicates that no character is pending at 
the keyboard. 


@ A one-character string contains the actual character read from the 
keyboard. 


@ A two-character string indicates a special extended ASCII code. 


No characters will be echoed. All characters are passed through to the 
program except for Ctrl-C which terminates the program. 


Example: 


1000 TIMED INPUT SUBROUTINE 

1010 RESPONSES=”” 

1020 FOR 1%=1 TO TIMELIMIT% 

1030 A$=INKEYS 

1035 IF LEN(A$)=0 THEN 1060 

1040 IF ASC(A$)=13 THEN TIMEOUT%=0 
1045 IF TIMEOUT%. = 0 THEN RETURN 
1050 RESPONSE$=RESPONSES+A$ 
1060 NEXT 1% 

1070 TIMEOUT%=1 : RETURN 
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7.59 INP FUNCTION 
Syntax: 
= IN P(1) 
Purpose: 
To return the byte read from port I. I must be in the range 0 to 65535. 
Remarks: 
INP is the complementary function to the OUT statement. 
Example: 
100 A=INP(54321) 
In 8086 assembly language, this is equivalent to: 


- MOV DX,54321 
IN AL,DX 
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7.60 INPUT STATEMENT 
Syntax: 

INPUT]{;] [<“prompt string’>;]<list of variables> 
Purpose: 
To allow input from the keyboard during program execution. 
Remarks: 


When an INPUT statement is encountered, program execution pauses and 
a question mark is printed to indicate the program is waiting for data. If 
<“prompt string”> is included, the string is printed before the question 
mark. The required data is then entered at the keyboard. 


BASIC can be re-directed to read from standard input and write to 
standard output by providing the input and output filenames when invok- 
ing BASIC. (See Section 2.1, “Invoking BASIC.”) 


A comma may be used instead of a semicolon after the prompt string to 
suppress the question mark. For example, the statement INPUT “ENTER 
BIRTHDATE”,B$ will print the prompt with no question mark. 


If INPUT is immediately followed by a semicolon, then the carriage return 
typed by the user to input data does not echo a carriage return/linefeed 
sequence. 


The data that is entered is assigned to the variable(s) given in <variable 
list>. The number of data items supplied must be the same as the number 
of variables in the list. Data items are separated by commas. 


The variable names in the list may be numeric or string variable names 
(including subscripted variables). The type of each data item that is input 
must agree with the type specified by the variable name. (Strings input to 
an INPUT statement need not be surrounded by quotation marks.) 
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Responding to INPUT with too many or too few items or with the wrong 
type of value (numeric instead of string, etc.) causes the message “?Redo 
from start” to be printed. No assignment of input values is made until an 
acceptable response is given. 


Examples: 


10 INPUT X 

20 PRINT X “SQUARED IS” X_ & 2 

30 END 

will yield 

2? 3 (The 5 was typed in by the user in response to the question mark.) 
5 SQUARED IS 25 


10 PI=3.14 

20 INPUT “WHAT IS THE RADIUS”;R 

30 A=PI*R_ & 2 

40 PRINT “THE AREA OF THE CIRCLE IS”;A 
50 PRINT 

60 GOTO 20 


will yield 
WHAT IS THE RADIUS? 7.4 (User types 7.4.) 
THE AREA OF THE CIRCLE IS 171.946 


WHAT IS THE RADIUS? 
etc. 
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7.61 INPUT# STATEMENT 
Syntax: 

INPUT#<file number>,<variable list> 
Purpose: 


To read data items from a sequential device or file and assign them to 
program variables. 


Remarks: 


<file number> is the number used when the file was OPENed for input. 
<variable list> contains the variable names that will be assigned to the 
items in the file. (The variable type must match the type specified by the 
variable name.) With INPUT#, no question mark is printed, as with 
INPUT. 


The data items in the file should appear just as they would if data were 
being typed in response to an INPUT statement. With numeric values, 
leading spaces, carriage returns, and linefeeds are ignored. The first char- 
acter encountered that is not a space, carriage return, or linefeed is 
assumed to be the start of a number. The number terminates on a space, 
carriage return, linefeed, or comma. 


If GW-BASIC is scanning the sequential data file for a string item, it will 
also ignore leading spaces, carriage returns, and linefeeds. The first char- 
acter encountered that is not a space, carriage return, or linefeed is 
assumed to be the start of a string item. If this first character is a quotation 
mark (“), the string item will consist of all characters read between the first 
quotation mark and the second. Thus, a quoted string may not contain a 
quotation mark as a character. If the first character of the string is not a 
quotation mark, the string is an unquoted string, and will terminate on a 
comma, carriage return, or linefeed (or after 255 characters have been 
read). If end-of-file is reached when a numeric or string item is being 
INPUT, the item is terminated. 


Example: 


INPUT#2,A,B,C 
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7.62 INPUT$ FUNCTION 
Syntax: 

INPUTS(X[[#]Y]) 
Purpose: 


To return a string of X characters, read from file number Y. If the file 
number is not specified, the characters will be read from the standard input 
device. If input has not been redirected, the keyboard is the standard input 
device. 


Remarks: 


If the keyboard is used for input, no characters will be echoed on the 
screen. All control characters are passed through except control C which is 
used to interrupt the execution of the INPUTS function. 


BASIC can be re-directed to read from standard input by providing the 
input filename on the command line. (See Section 2.1, “Invoking BASIC.”) 


Example 1: 


5 LIST THE CONTENTS OF A SEQUENTIAL FILE IN 
HEXADECIMAL 

10 OPEN“I”,1,“DATA” 

20 IF EOF(1) THEN 50 

30 PRINT HEX$(ASC(INPUTS$(1,#1))); 

40 GOTO 20 

50 PRINT 

60 END 


Example 2: 


100 PRINT “TYPE P TO PROCEED OR S TO STOP” 
110 X$=INPUTS(1) 

120 IF X$=“P” THEN 500 

130 IF X$=“S” THEN 700 ELSE 100 
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7.63 INSTR FUNCTION 
Syntax: 

INSTR({I,]X$, YS) 
Purpose: 


To search for the first occurrence of string Y$ in X$, and to return the 
position at which the match is found. Optional offset I sets the position for 
starting the search. 


Remarks: 


I must be in the range | to 255. If lis greater than the number of characters 
in X$(LEN(X$)), or if X$ is null or Y$ cannot be found, INSTR returns 0. 
If Y$ is null, INSTR returns I or 1, and if no I was specified, then INSTR 
returns |. X$ and Y$ may be string variables, string expressions, or string 
literals. 


Example: 


10 X$=“ABCDES” 
20 Y$=“B” 
30 PRINT INSTR(X$,Y$);INSTR(4,X$, Y$) 


will yield 
2 6 
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7.64 INT FUNCTION 
Syntax: 
INT(X) 
Purpose: 
To return the largest integer <=X. 
Examples: 


PRINT INT(99.89) 
will yield 
99 


PRINT INT(-12.11) 
will yield 
-13 


See the CINT and FIX functions, Sections 7.14 and 7.49, respectively, 
which also return integer values. 
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7.65 IOCTL STATEMENT 
Syntax: 
IOCTL [#]<filenumber>, <string> 
Purpose: 
To transmit a control character or string to a device driver. 
Remarks: 
IOCTL commands are generally two to three characters followed option- 
ally by an alphanumeric argument. An IOCTL$ command string may be 
up to 255 bytes long. 
The IOCTL statement works only if: 


1. The device driver is installed. 
2. The device driver states it processes IOCTL strings. 
3. BASIC performs an OPEN on a file on that device. 


Most standard MS-DOS device drivers don’t process IOCTL strings, and 
it is necessary for the programmer to determine whether the specific driver 
can handle the command. 


Example: 


If a user wanted to set the page length to 66 lines per page on LPT1, the 
procedure might be: 


10 OPEN “\DEV\LPT1” FOR OUTPUT AS #1 
20 IOCTLS$ #1, “PL66” 


Also see the IOCTLS$ Function. 
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7.66 IOCTL$ FUNCTION 
Syntax: 
IOCTLS ({#]<filenumber>) 
Purpose: 
To receive a control data string from a device driver. 
Remarks: 
The IOCTLS function is most frequently used to receive acknowledge- 
ment that an IOCTL statement succeeded or failed, or to obtain current 


status information. 


IOCTL$ could be used to ask a communications device to return the 
current baud rate, information on the last error, logical line width, etc. 


The IOCTLS function works only if: 


1. The device driver is installed. 
2. The device driver states it processes IOCTL strings. 
3. BASIC performs an OPEN on a file on that device. 


Example: 


10 OPEN “\DEV\FOO” AS #1 
20 IOCTL #1, “RAW” 


This example tells the device that the data is raw. 
30 IF IOCTL$(1) = “0” THEN CLOSE 1 


In this continuation, if the Character Driver FOO’ responds ’false’ from 
the raw data mode IOCTL statement, then the file is closed. 


Also see the IOCTL Statement. 
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7.67 KEY STATEMENT 
Syntax: 
KEY n, X$ 
KEY LIST 
KEY ON 
KEY OFF 
n is the number of the function key (in the range | to 12). 
X$ is the text assigned to the specified key. 
Purpose: 
To assign softkey values to function keys and display the values. 
Remarks: 
The KEY statement allows function keys to be designated for special 
“softkey” functions. Each of the function keys may be assigned a 15-byte 


string which will be input to GW-BASIC when that key is pressed. 


Initially, the “softkeys” are assigned the following values: 


Fl LIST F2 AUTO 

F3 RUN- F4 LOAD” 

FS SAVE” F6 CONT 

F/ , LPT: F8 TRON 

F9 TROFF— F10 KEY 

Fll EDIT + F12 SCREEN 0,0,0— 


The arrow (+) indicates Enter and (_) indicates space. 


Softkeys can be displayed with the KEY ON, KEY OFF, and KEY LIST 
statements. 


KEY ON causes the softkey values to be displayed on the bottom line of 
the screen. 


KEY OFF erases the softkey display from the bottom line, making that 
line available for program use. It does not disable the function keys. 
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KEY LIST displays all softkey values on the screen, with all 15 characters 
of each key displayed. 


Assigning a null string (string of length 0) to a softkey disables the function 
key as a softkey. 


If the function key number is not in the range of permissible function key 
numbers, an “Illegal function call” error is produced, and the previous key 
string expression is retained. 


When a softkey is assigned, the INKEY$ function returns one character of 
the softkey string per invocation. If the softkey is disabled, INKEY$ 
returns a two-character string. 


Example: 


50 KEY ON ’Displays the softkey on bottom line 
60 KEY OFF’ Erases softkey display 
70 KEY 1,*MENU”+CHR§(13) ’ 


Assigns the string “MENU” followed by a carriage return to softkey 1. 
Such assignments might be used to speed data entry. 
80 KEY 1,“” Disables softkey 1 
The following routine initializes the first five softkeys: 
10 KEY OFF Turns off key display during initialization 
20 DATA “EDIT ”,“LET ”,“SYSTEM”,“PRINT ”,“LPRINT ” 
30 FOR I=1TO5 
40 READ SOFTKEYS&I) 
50 KEY I,SSOFTKEYS(I) 


60 NEXT I 
70 KEY ON Displays new softkeys 
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7.68 KEY(n) STATEMENT 
Syntax: 

KEY(n) ON 

KEY(n) OFF 

KEY(n) STOP 
where (n) is the number of a function key, help key, a user-defined key. 
These keys are numbered sequentially after the function keys (1~12) inthe 
following order: up (13), left (14), right (15), down (16); then come the 
user-defined keys (17~22). 
User Defined keys are defined by the statement: 

KEY 1,CHR$QG)+CHR$(k) 


11s the number of a user-defined key in the range 17 to 22. 


jisascan code inthe range 0 to 117. See Appendix E, “Keyboard Diagram 
and Scan Codes.” 


k is an ASCII character code in the range | to 254. See Appendix A, 
“ASCII Character Code.” 


KEY(n) OFF disables the event trap. If an event takes place, it is not 
remembered. 
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KEY(n) STOP disables the event trap, but if an event occurs, it is remem- 
bered and an ON KEY statement will be executed as soon as trapping is 
enabled. 


NOTE 


For additional information on key 
event trapping, see “Event Trapping,” 
Section 6.2, and “ON KEY State- 
ment,” Section 7.97. 


Example: 


10 KEY 4,SCREEN 0,0 ’ assigns softkey 4 
20 KEY(4) ON ’enables event trapping 


70 ON KEY(4) GOSUB 200 
key 4 pressed 


200 ’*Subroutine for screen 
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7.69 KILL STATEMENT 
Syntax: 
KILL [<filespec>] 
Purpose: 
To delete a file or a pathname from disk. 
Remarks: 


Ifa KILL statement is given fora file that is currently open, a “File already 
open” error occurs. 


KILL is used for all types of disk files: program files, random data files, 
and sequential data files. The filespec may contain question marks (?) or 
asterisks (*) used as wildcards. A question mark will match any single 
character in the filename or extension. An asterisk will match one or more 
characters starting at its position. 


Since it is possible to reference the same file in a sub-directory via different 
paths, it is nearly impossible for BASIC to know that it is indeed the same 
file simply by looking at the path. For example, if MARY is your current 
directory, then: 


“REPORT” ... 
“\SALES\MARY\REPORT” ... 
“..MARY\REPORT” ... 
“\.NMARY\REPORT” ... 


all refer to the same file. Therefore, any open file with the same file name 
will cause a “file already open” error. 


WARNING 


Be extremely careful when using wild- 
cards with this command. 
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Examples: 

200 KILL “DATAI1?.DAT” 
The position taken by the question mark will match any valid filename 
character. This command will kill any file that has a six character name 
starting with “DATAI1” and has the filename extension “.DAT”. This 
includes “DATA10.DAT” and “DATAIZ.DAT”. 

210 KILL “DATAI.*” 
Kills all files named DATAI, regardless of the filename extension. 


220 KILL “..\GREG\*.DAT” 


Kills all files with the extension “.DAT” in a directory called GREG. 
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7.70 LEFT$ FUNCTION 
Syntax: 
LEFT$(<string>,]) oS 
Purpose: 
To return a string comprising the leftmost I characters of X$. 
Remarks: 
I must be in the range 0 to 255. If I is greater than the number of characters 
in <string>, (LEN(X$)), the entire string (<string>) will be returned. If I 
= 0, the null string (length zero) is returned. 


Example: 


10 A$=“BASIC LANGUAGE” 
20 B$=LEFT$(A$,5) 


30 PRINT B$ J 
will yield | 
BASIC 
Also see the MID$ and RIGHTS functions, Sections 7.88 and 7.133, 
respectively. 
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7.71 LEN FUNCTION 
Syntax: 

LEN(<string>) 
Purpose: 


To return the number of characters in <string>. Nonprinting characters 
and blanks are counted. 


Example: 


10 X$=“PORTLAND, OREGON” 
20 PRINT (LEN(X$) 

will yield 

16 


7-95 


Basic Commands, Functions and Statements 


7.72 LET STATEMENT 
Syntax: 
[LET ]<variable>=<expression> 
Purpose: 
To assign the value of an expression to a variable. 
Remarks: 


Notice that the word LET is optional; 1.e., the equal sign is sufficient for 
assigning an expression to a variable name. 


Example: 


110 LET D=12 

120 LET E=12 “2 

130 LET F=12 ~*~ 4 
140 LET SUM=D+E+F 


OT 


110 D=12 

120 E=12 * 2 
130 F=12 S 4 
140 SUM=D+Et+F 
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7.73 LINE STATEMENT 
Syntax: 


LINE [[STEP](x1,y1)]-[STEP](x2,y2) 
[.[<color>][,b[f]]][. style] 


(xl,y1) is the coordinate for the starting point of the line. 
(x2,y2) is the ending point for the line. 


The [STEP] option makes the specified coordinates relative to the “most 
recent point,” instead of absolute, mapped coordinates. 


<color> is the color number in the range 0 to 7 and selects the color from 
the current palette as defined by the COLOR statement. 0 is the back- 


ground color. The default is the foreground color. 


,b draws a box with the points (x1,y1) and (x2,y2) specifying the upper left 
and lower right corners. 


,bf draws a filled box. 


,style is a 16-bit integer mask used when putting pixels down on the screen. 
This is called “line styling.” 


Purpose: 
To draw a line or box on the screen. 
Remarks: 


When coordinates specify a point that is not in the current viewport, the 
line segment is clipped to the viewport. 


The relative coordinate form STEP (xoffset,yoffset) can be used in place 
of an absolute coordinate. For example, assume that the most recent point 
referenced was (10,10). The statement LINE STEP (10,5) would specify a 
point at offset 10 from x and offset 5 from y, that is, (20,15). 
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If the STEP option is used for the second coordinate ona LINE statement, 
it is relative to the first coordinate in the statement. Other ways to establish 
a new “most recent point” are to initialize the screen with the CLS and 
SCREEN statements (Sections 7.18 and 7.138, respectively). Using the 
PSET, PRESET, CIRCLE and DRAW statements will establish a new 
“most recent point.” 


Each time LINE stores a point on the screen, it uses the current circulating 
bit in [style]. If that bit is a 0, then no storing will be done; if the bit is a I, 
the point is stored. After each point is stored, the next bit position in [style] 
is selected. Since a 0 bit in [style] causes no change to the point on the 
screen, the user may prefer to draw a background line before a ‘styled’ line 
in order to force a known background. Style is used for normal lines and 
boxes, but has no effect on filled boxes. 

Examples: 


The following examples assume a screen 320 pixels wide by 200 pixels 
high. 


10 LINE -(x2,y2) 
Draws a line from the last point to x2,y2 in the foreground color. 
20 LINE (0,0)-(319, 199) 
Draws a diagonal line across the screen (downward). 
30 LINE (0,100)-(319, 100) 
Draws a line across the screen. 
40 LINE (10,10)-(20,20),2 
Draws a line in color 2. 


10 FOR x=0 to 319 
20 LINE (x,0)-(x,199),x AND 1 
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Draws an alternating line on-line off pattern on a monochrome display. 
10 LINE (0,0)-(100,100),,b 

Draws a box in the foreground (note that the color is not included). 
20 LINE STEP (0,0)-STEP (200,200),2, bf 

Draws a filled box in color 2. Coordinates are given as offsets. 
10 LINE (0,0)-(160,100),3,,&HFFOO 


Draws a dashed line from the upper left hand corner to the center of the 
screen. 
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7.74 LINE INPUT STATEMENT 
Syntax: 


LINE INPUT];] [<“prompt string’”>;] 
<string variable> 


Purpose: 


To input an entire line (up to 254 characters) to a string variable, without 
the use of delimiters. 


Remarks: 


<“prompt string’’> is a string literal that is printed at the terminal before 
input is accepted. A question mark is not printed unless it is part of 
<“prompt string”>. All input from the end of <“prompt string”> to the 
carriage return is assigned to <string variable>. However, if a linefeed / 
carriage return sequence (this order only) is encountered, both characters 
are echoed; but the carriage return is ignored, the linefeed is put into 
<string variable>, and data input continues. 


If LINE INPUT is immediately followed by a semicolon, then the carriage 
return typed by the user to end the input line does not echo a carriage 
return/linefeed sequence at the terminal. 

A LINE INPUT statement may be aborted by typing Control-C. GW- 
BASIC will return to command level. If you are using the interpreter, 
typing CONT resumes execution at the LINE INPUT. 


Example: 


See LINE INPUT# Statement, Section 7.75. 
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7.75 LINE INPUT# STATEMENT 
Syntax: 

LINE INPUT#<file number>,<string variable> 
Purpose: 


To read an entire line (up to 254 characters), without delimiters, from a 
sequential disk data file to a string variable. 


Remarks: 


<file number> is the number under which the file was OPENed. <string 
variable> is the variable name to which the line will be assigned. LINE 
INPUT# reads all characters in the sequential file up to a carriage return. It 
then skips over the carriage return/linefeed sequence. The next LINE 
INPUT# reads all characters up to the next carriage return. (Ifa linefeed / 
Carriage return sequence is encountered, it is preserved.) 


LINE INPUT# is especially useful if each line of a data file has been 
broken into fields, or if a GW-BASIC program saved in ASCII format is 
being read as data by another program. (See SAVE Command, Section 
7.137.) 


When GW-BASIC 1s invoked with redirected input and output, all LINE 
INPUT statements will read from the input file specified instead of the 
keyboard. 
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When input is redirected, GW-BASIC will continue to read from this 
source until a control-Z is detected. This condition may be tested with the 
EOF function. If the file is not terminated by a control-Z, or a BASIC file 
input statement tries to read past end-of-file, then any open files are closed, 
the message “Read past end” is written to standard output, and BASIC 
returns to MS-DOS. 


Example: 


10 OPEN “O”,1,“LIST” 

20 LINE INPUT “CUSTOMER INFORMATION? ”;C$ 
30 PRINT #1, C$ 

40 CLOSE | 

50 OPEN “I”,1,“LIST” 

60 LINE INPUT #1, C$ 

70 PRINT C$ 

80 CLOSE | 


will yield 


CUSTOMER INFORMATION? LINDA JONES 234,4 MEMPHIS 
LINDA JONES 234,4 MEMPHIS 
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7.76 LIST COMMAND 
Syntax: 

LIST [<line number>] [-[<line number>]] [,<device>] 
<line number> is in the range 0 to 65529. 


<device> is a device designation string, such as SCRN: or LPT:, ora 
filename. 


Purpose: 

To list all or part of the program currently in memory. 

Remarks: 

GW-BASIC always returns to command level after a LIST 1s executed. 
If <line number> is omitted, the program is listed beginning at the lowest 
line number. (Listing is terminated either when the end of the program is 
reached or by typing Break.) If <line number> is included, only the 


specified line will be listed. 


If only the first <line number> is specified, that line and all higher- 
numbered lines are listed. 


If only the second <line number> is specified, all lines from the beginning 
of the program through that line are listed. 


If both <line number(s)> are specified, the entire range is listed. 


If the <device> is omitted, the listing is shown at the terminal. 
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Examples: 
LIST 

Lists the program currently in memory. 
LIST 500 

Lists line 500. 
LIST 150- 

Lists all lines from 150 to the end. 
LIST -1000 

Lists all lines from the lowest number through 1000. 
LIST 150-1000 

Lists lines 150 through 1000, inclusive. 
LIST 150-1000,“LPT:” 


Lists lines 150 through 1000 on the line printer. 
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7.77 LLIST COMMAND 
Syntax: 
LLIST [<line number>[-[<line number>]]] 
Purpose: 
To list all or part of the program currently in memory on the line printer. 
Remarks: 
LLIST assumes a 132-character-wide printer. 
GW-BASIC always returns to command level after an LLIST is executed. 
The options for LLIST are the same as for the LIST Command, Section 
7.76. 
Example: 
See the examples for the LIST Command, Section 7.76. With the excep- 


tion of the last one, which addresses a device, LLIST will work ina similar 
way. 
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7.78 LOAD COMMAND 
Syntax: 

LOAD <filespec>[,R] 
Purpose: 
To load a file from an input device into memory. 
Remarks: 
For loading a program, the <filespec> is an optional device specification 
followed by a filename or pathname that conforms to MS-DOS 2.0’s rules 
for filenames. BASIC appends the default filename extension .BAS if the 
user specifies no extensions, when the file is saved to the disk. 
The <filespec> must include the filename that was used when the file was 
saved, or created by an editor. (BASIC will append a default filename 
extension if one was not supplied in the SAVE command.) 
The R option automatically runs the program after it has been loaded. 
LOAD closes all open files and deletes all variables and program lines 
currently residing in memory before it loads the designated program. 
However, if the R option is used with LOAD, the program is run after it is 
loaded, and all open data files are kept open. Thus, LOAD with the R 
option may be used to chain several programs (or segments of the same 
program). Information may be passed between the programs using their 
disk data files. 
Example: 

LOAD “STRTRK”,R 
Loads and runs the program STRTRK.BAS 

LOAD “B:MYPROG” 


Loads the program MYPROG.BAS from the disk in drive B, but does not 
run the program. 
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7.79 LOC FUNCTION 
Syntax: 
LOC(<file number>) 
where <file number> is the number under which the file was opened. 
Purpose: 


With random disk files, LOC returns the actual record number within the 
file. 


With sequential files, LOC returns the current byte position in the file, 
divided by 128. 


Remarks: 


When a file is opened for APPEND or OUTPUT, LOC returns the size of 
the file in (bytes / 128). 


For a communications file, LOC(X) is used to determine if there are any 
characters in the input queue waiting to be read. If there are more than 255 
characters in the queue, LOC(X) returns 255. Since interpreter strings are 
limited to 255 characters, this practical limit alleviates the need for an 
interpreter user to test for string size before reading data into it. 


If fewer than 255 characters remain in the queue, the value returned by 
LOC(X) depends on whether the device was opened in ASCII or binary 
mode. In either mode, LOC will return the number of characters that can 
be read from the device. However, in ASCII mode, the low level routines 
stop queueing characters as soon as end-of-file is received. The end-of-file 
itself is not queued and cannot be read. An attempt to read the end-of-file 
will result in an “Input past end” error. 


Example: 


200 IF LOC(1)>50 THEN STOP 
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7.80 LOCATE STATEMENT 
Syntax: 
LOCATE [row]f[,[col][,[cursor][,[start][ stop ]]]] 


<row> isa line number (vertical) on the screen. Row should be a numeric 
expression returning an unsigned integer. 


<col> is the column number on the screen. It should be a numeric 
expression returning an unsigned integer. 


<cursor> is a Boolean value indicating whether the cursor should be 
visible or not. 


<start> is the cursor starting line (vertical) on the screen. It should be a 
numeric expression returning an unsigned integer. 


<stop> is the cursor stop line (vertical) on the screen. It should be a 
numeric expression returning an unsigned integer. 


Purpose: 


Moves the cursor to the specified position. Optional parameters turn the 
blinking cursor on and off and define the vertical start and stop lines. 


Remarks: 


Any value outside the specified ranges will result in an “Illegal function 
call” error. In this case, previous values are retained. 


Any parameter may be omitted from the statement. If a parameter is 
omitted, the previous value is assumed. 


Note that the <start> and <stop> lines are the raster lines that specify 
which pixels on the screen are lit. A wider range between the start and stop 
lines will produce a taller cursor, such as one that occupies an entire 
character block. 


If the <start> line is given but the <stop> line is omitted, <stop> 
assumes the same value as <start>. 
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The last line on the screen is reserved for softkey display and is not 
accessible to the cursor unless the softkey display is off and LOCATE 1s 
used to get to it. 
Example: 

10 LOCATE 1,1 
Moves cursor to upper-left corner of the screen. 

20 LOCATE ,,1 
Makes the cursor visible; position remains unchanged. 


30 LOCATE ,,,7 


Position and cursor visibility remain unchanged. Sets the cursor to display 
at the bottom of the character starting and ending on raster line 7. 


40 LOCATE 5,1,1,0,7 


Moves the cursor to line 5, column 1; turns cursor on. Cursor will cover 
entire character cell starting at scan line 0 and ending on scan line 7. 


7-109 


Basic Commands, Functions and Statements 


7.81 LOF FUNCTION 
Syntax: 
LOF(<file number>) 
Purpose: 
To return the length of the named file in bytes. 
Remarks: 


When a file is opened for APPEND or OUTPUT, LOF returns the size of 
the file, in bytes. 


Example: 


110 IF REC*RECSIZ>LOF(1) 
THEN PRINT “INVALID ENTRY” 


In this example, the variables REC and RECSIZ contain the record 


number and record length, respectively. The calculation determines 
whether the specified record is beyond the end-of-file. 
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To return the natural logarithm of X. X must be greater than zero. 


Example: 


PRINT LOG(45/7) 
will yield 
1.860752 


7-111 


Basic Commands, Functions and Statements 


7.83 LPOS FUNCTION 
Syntax: 
LPOS(X) 


where X is the index of the printer being tested; that is LPT1: would be 
tested with LPOS(1), LPT2: with LPOS(2), etc. 


Purpose: 


To return the current position of the printer’s print head within the printer 
buffer. 


Remarks: 


LPOS does not necessarily give the physical position of the print head. 


Example: 


100 IF LPOS(X)>60 THEN LPRINT CHR$(13) 
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7.84 LPRINT AND LPRINT USING STATEMENTS 
Syntax: 


LPRINT [<dist of expressions>] 
LPRINT [<string exp>;<list of expressions> 


Purpose: 

To print data on the printer. 

Remarks: 

Same as PRINT and PRINT USING, except output goes to the line 
printer, and the file number option is not permitted. See Sections 7.119 


and 7.120, respectively. 


LPRINT assumes a 132-character-wide printer. However, the width may 
vary according to your implementation. 


Examples: 


See Sections 7.119 and 7.120. 
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7.85 LSET AND RSET STATEMENTS 
Syntax: 


LSET <string variable>=<string expression> — 
RSET <string variable>=<string expression> 


Purpose: 


To move data from memory to a random file buffer (in preparation for a 
PUT statement) or to left- or right-justify the value of a string into a string 
variable. 


Remarks: 


If <string expression> requires fewer bytes than were fielded to <string 
variable>, LSET left-justifies the string in the field, and RSET right- 
justifies the string. (Spaces are used to pad the extra positions.) If the string 
is too long for the field, characters are dropped from the right. Numeric 
values must be converted to strings before they are LSET or RSET. See 
MKI$, MKS$, MKD$ functions, Section 7.90. . 


Examples: 


150 LSET A$=MKS$(AMT) 
160 LSET D$=MKI$(COUNT%) 


NOTE 


LSET or RSET may also be used with 
a nonfielded string variable to left- 
justify or right-justify a string in a 
given field. For example, the program 
lines 


110 A$=SPACE$(20) 

120 RSET A$=N$ 
right-justify the string N$ in a 20- > 
character field. This can be very handy — 
for formatting printed output. 
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7.86 MERGE COMMAND 
Syntax: 

MERGE <filespec> 
Purpose: 
To merge a specified file into the program currently in memory. 
Remarks: 
For merging a program not in memory, the <filespec> is an optional 
device specification followed by a filename or pathname that conforms to 
MS-DOS 2.0’s rules for filenames. BASIC appends the default filename 
extension “.BAS” if the user specifies no extensions, and the file has been 
saved to the disk. 
If any lines in the disk file have the same line numbers as lines in the 
program in memory, the lines from the file on disk will replace the 
corresponding lines in memory. (MERGEing may be thought of as “insert- 


ing” the program lines on disk into the program in memory.) 


Microsoft GW-BASIC always returns to command level after executing a 
MERGE command. 


Example: 
MERGE “NUMBRS” 


Inserts, by sequential line number, all lines in the program NUMBRS.- 
BAS into the program currently in memory. 
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7.87 MID$ STATEMENT 
Syntax: 
MID$(<string 1>,n[,m])=<string 2> 


where n and m are integer expressions and <string exp|> and <string 
exp2> are string expressions. 


Purpose: 
To replace a portion of one string with another string. 
Remarks: 


The characters in <string |>, beginning at position n, are replaced by the 
characters in <string 2>. The optional “m” refers to the number of 
characters from <string 2> that will be used in the replacement. If ““m” 1s 
omitted, all of <string 2> is used. However, regardless of whether “m” is 
omitted or included, the replacement of characters never goes beyond the 
original length of <string 1>. 


Example: 


10 A$=KANSAS CITY, MO” 
20 MID$(A$, 14)=“KS” 
30 PRINT A$ 


will yield 
KANSAS CITY, KS 


MID$ is also a function that returns a substring of a given string. See 
Section 7.88. 
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7.88 MID$ FUNCTION 
Syntax: 

MID§$(<string>,n[,m]) 
Purpose: 


To return a string of length m characters from X$, beginning with the nth 
character. 


Remarks: 


n and m must be in the range | to 255. If m is omitted or if there are fewer 
than m characters to the right of the nth character, all rightmost characters 
beginning with the nth character are returned. If n is greater than the 
number of characters in <string>, that is, (LEN(<string>)), MID$ 
returns a null string. 


Example: 


10 A$=“GOOD ” 
20 B$=“MORNING EVENING AFTERNOON” 
30 PRINT A$;MIDS$(B$,9,7) 


will yield 
GOOD EVENING 


Also see the LEFT$ and RIGHTS$ functions, Sections 7.70 and 7.133, 
respectively. 
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7.89 MKDIR STATEMENT 
Syntax: 

MKDIR <pathname> 
Purpose: 
To create a new directory. 
Remarks: 
<pathname> is a string expression specifying the name of the directory 
which is to be created. MK DIR works exactly like the MS-DOS command 
MKDIR. The <pathname> must be a string of less than 128 characters. 
(See Section 5.5, “File Handling,” for a discussion of tree-structured 
directories. ) 
Example: 
Assume the current directory is the root. 


MKDIR “SALES” 


Creates a sub-directory named SALES in the current directory of the 
current drive. 


MKDIR “B:USERS 
Creates a sub-directory named USERS inthe current directory of drive B. 


Also see the CHDIR and RMDIR statements, Sections 7.12 and 7.134, 
respectively. 
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7.90 MKI$, MKS$, MKD$ FUNCTIONS 
Syntax: 
MKI$(<integer expression>) 
MKS$(<single precision expression>) 
MKD$(<double precision expression>) 
Purpose: 


To convert numeric values to string values. 


Remarks: 


Any numeric value that is placed in a random file buffer with an LSET or 
RSET statement must be converted to a string. MKI$ converts an integer 
to a 2-byte string. MKS$ converts a single precision number to a 4-byte 
string. MK D§ converts a double precision number to an 8-byte string. 


Example: 


90 AMT=(K+T) 

100 FIELD #1,8 AS D$,20 AS N$ 
110 LSET D$=MKS$(AMT) 

120 LSET N$=A$ 

130 PUT #1 


See also CVI, CVS, CVD Functions, Section 7.26. 
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7.91 NAME STATEMENT 
Syntax: 
NAME <old filename> AS <new filename> 
Purpose: 
To change the name of a disk file. 
Remarks: 


<old filename> must exist and <new filename> must not exist; other- 
wise, an error will result. Also, both files must be on the same drive. 


A file may not be renamed with a new drive designation. If this is attempt- 
ed, a “Rename across disks” error will be generated. After a NAME 
command, the file exists on the same disk with the new name. 


NAME may not be used to rename directories. 


<old filename> must be closed before the renaming command Is exe- 
cuted. Also, there must be one free file handle. 


Examples: 
NAME “ACCTS” AS “LEDGER” 


In this example, the file that was formerly named ACCTS will now be 
named LEDGER. 


NAME may be used to move a file from one directory to another. For 
example: 


NAME “\X\CLIENTS” AS “\XYZ\P\CLIENTS” 
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7.92 NEW COMMAND 
Syntax: 

NEW 
Purpose: 
To delete the program currently in memory and clear all variables. 
Remarks: 
NEW is entered in direct mode to clear memory before entering a new 
program. Microsoft GW-BASIC always returns to command level after a 
NEW is executed. 
NEW closes all files and turns tracing off. 


Example: 


NEW 


7-121 


Basic Commands, Functions and Statements 


7.93 OCTS$(X) 
Purpose: 


To return a string that represents the octal value of the decimal argument. 
X is rounded to an integer before OCT$(X) is evaluated (-32768~65535). 


Example: 


PRINT OCT$(24) 
will yield 
30 


See the HEX$ function, Section 7.56, for details on hexadecimal 
conversion. 
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7.94 ON COM STATEMENT 
Syntax: 
ON COM(1) GOSUB <line number> 


where <line number> is the number of the first line of a subroutine that is 
to be performed when activity occurs on the communications port. 


Purpose: 


To specify the first line number of a subroutine to be performed when 
activity occurs on a communications port. 


Remarks: 
A <line number> of zero disables the communications event trap. 


The ON COM statement will only be executed if a COM(1) ON statement 
has been executed (see COM Statement, Section 7.20) to enable event 
trapping. If event trapping is enabled, and if the <line number> inthe ON 
COM statement is not zero, GW-BASIC checks between statements to see 
if communications activity has occurred on the specified port. If communi- 
cations activity has occurred, a GOS UB will be performed to the specified 
line. 


Ifa COM OFF statement has been executed for the communications port 
(see COM Statement, Section 7.20), the GOSUB is not performed and is 
not remembered. 


If a COM STOP statement has been executed for the communications 


port (see COM Statement, Section 7.20), the GOSUB is not performed, 
but will be performed as soon as a COM ON statement is executed. 
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When an event trap occurs (i.e., the GOSUB is performed), an automatic 
COM STOP is executed so that recursive traps cannot take place. The 
RETURN from the trapping subroutine will automatically perform a 
COM ON statement unless an explicit COM OFF was performed inside 
the subroutine. 


The RETURN <line number> form of the RETURN statement may be 
used to return to a specific line number from the trapping subroutine. Use 
this type of return with care, however, because any other GOSUBs, 
WHILEs, or FORs that were active at the time of the trap will remain 
active, and errors such as “FOR without NEXT” may result. 


Event trapping does not take place when GW-BASIC is not executing a 


program, and event trapping is automatically disabled when an error trap 
occurs. 
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7.95 ON ERROR GOTO STATEMENT 
Syntax: 

ON ERROR GOTO <line number> 
Purpose: 


To enable error handling and specify the first line of the error handling 
routine. 


Remarks: 


Once error handling has been enabled, all errors detected, including direct 
mode errors (e.g., syntax errors), will cause a jump to the specified error 
handling routine. If <line number> does not exist, an “Undefined line” 
error results. 


To disable error handling, execute an ON ERROR GOTO 0. Subsequent 
errors will print an error message and halt execution. An ON ERROR 
GOTO 0 statement that appears in an error handling routine causes 
Microsoft GW-BASIC to stop and print the error message for the error 
that caused the trap. It is recommended that all error handling routines 
execute an ON ERROR GOTO 0if an error is encountered for which there 
is NO recovery action. 


NOTE 


If an error occurs during execution of 
an error handling routine, that error 
message is printed and execution ter- 
minates. Error trapping does not 
occur within the error handling rou- 
tine. 


Example: 


10 ON ERROR GOTO 1000 
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7.96 ON...GOSUB AND ON...GOTO STATEMENTS 
Syntax: 


ON <expression> GOTO <list of line numbers> 
ON <expression> GOSUB <list of line numbers> 


Purpose: 


To branch to one of several specified line numbers, depending on the value 
returned when an expression is evaluated. 


Remarks: 

The value of <expression> determines which line number in the list will 
be used for branching. For example, if the value is three, the third line 
number in the list will be the destination of the branch. (If the value is a 


noninteger, the number is rounded.) 


In the ON...GOSUB statement, each line number in the list must be the 
first line number of a subroutine. 


If the value of <expression> is either zero or greater than the number of 
items in the list, control drops to the next BASIC statement. 


If the value of <expression> is negative or greater than 255, an “Illegal 
function call” error occurs. 


Example: 


100 ON L-1 GOTO 150,300,320,390 
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In the above, the programmer has overridden the normal function asso- 
ciated with function key 4, and replaced it with “SCREEN 0,0”, which will 
be printed whenever that key is pressed. The value may be reassigned and it 
will resume its standard function when the machine is rebooted. 


100 KEY 12, CHR$(&H04) + CHR$(83) 
110 KEY(12) ON 


1000 PRINT “If you want to stop processing for a break” 
1010 PRINT “press the Control key and the ‘S’ at the” 
1020 PRINT “same time.” 

1030 ON KEY(12) GOSUB 3000. 


Operator presses Control-S 


3000 REM ** Suspend processing loop. 
3010 CLOSE #1 

3020 RESET 

3030 CLS 

3035 PRINT “Enter CONT to continue.” 
3040 STOP 

3050 OPEN “A”, #1, “ACCOUNTS.DAT” 
3060 RETURN 


In the above, the programmer has enabled the Control-S key to enter a 


subroutine which closes the files and stops program execution until the 
operator is ready to continue. 
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7.97 ON KEY STATEMENT 
Syntax: 
ON KEY(n) GOSUB <line number> 
(n) is the number of a function key, direction key, or user-defined key. 


<line number> is the number of the first line of a subroutine that is to be 
performed when the specified function or cursor direction key is pressed. 


Purpose: 


To specify the first line number of a subroutine to be performed when a 
specified key is pressed. 


Remarks: 
A <line number> of zero disables the event trap. 


The ON KEY statement will only be executed if a KEY(n) ON statement 
has been executed (see KEY(n) Statement, Section 7.68) to enable event 
trapping. If key trapping is enabled, and if the <line number> in the ON 
KEY statement is not zero, GW-BASIC checks between statements to see 
if the specified function, user-defined or cursor direction key has been 
pressed. If so, the program will branch to a subroutine specified by the 
GOSUB statement. 


If a KEY(n) OFF statement has been executed for the specified key (see 
KEY(n) Statement, Section 7.68), the GOS UB is not performed and is not 
remembered. 


If a KEY STOP statement has been executed for the specified key (see 
KEY(n) Statement, Section 7.68), the GOSUB is not performed, but will 
be performed as soon as a KEY(n) ON statement is executed. 


When an event trap occurs (i.e., the GOSUB is performed), an automatic 
KEY(n) STOP is executed so that recursive traps cannot take place. The 
RETURN from the trapping subroutine will automatically perform a 
KEY(n) ON statement unless an explicit KEY(n) OFF was performed 
inside the subroutine. 
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The RETURN <dine number> form of the RETURN statement may be 
used to return to a specific line number from the trapping subroutine. Use 
this type of return with care, however, because any other GOSUBs, 
WHILEs, or FORs that were active at the time of the trap will remain 
active, and errors such as “FOR without NEXT” could result. 


Event trapping does not take place when GW-BASIC is not executing a 
program, and event trapping is automatically disabled when an error trap 
occurs. 


WARNING 


This may apply to any key, including 
Break or system reset (warm boot)! 
This is a powerful feature when you 
consider that it is now possible to pre- 
vent BASIC Application users from 
accidentally Breaking out of a pro- 
gram, or worse yet, rebooting the 
machine. 


NOTE 


When a key 1s trapped, that occur- 
rence of the key is destroyed. There- 
fore, you cannot subsequently use the 
INPUT or INKEY$ statements to 
find out which key caused the trap. So 
if you wish to assign different func- 
tions to particular keys, you must set 
up a different subroutine for each 
key, rather than assigning the various 
functions within a single subroutine. 


7-129 


Basic Commands, Functions and Statements 


7.98 ON PEN STATEMENT 
Syntax: 
ON PEN GOSUB <line number> 


where <line number> is the number of the first line of asubroutine that is 
to be performed when the lightpen is activated. 


Purpose: 


To specify the first line number of a subroutine to be performed when the 
lightpen is activated. 


Remarks: 
A <line number> of zero disables the pen event trap. 


The ON PEN statement will only be executed if a PEN ON statement has 
been executed (see PEN ON Statement and PEN Function, Sections 7.109 
and 7.110) to enable event trapping. If event trapping is enabled, and if the 
<line number> inthe ON PEN statement is not zero, GW-BASIC checks 
between statements to see if the lightpen has been activated. If the lightpen 
has been activated, a GOSUB will be performed to the specified line. 


If a PEN OFF statement has been executed (see PEN OFF Statement, 
Section 7.109), the GOSUB is not performed and is not remembered. 


Ifa PEN STOP statement has been executed (see PEN STOP Statement, 


Section 7.109), the GOSUB is not performed, but will be performed as 
soon as a PEN ON statement is executed. 
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When an event trap occurs (1.e., the GOSUB is performed), an automatic 
PEN STOP is executed so that recursive traps cannot take place. The 
RETURN from the trapping subroutine will automatically perform a 
PEN ON statement unless an explicit PEN OFF was performed inside the 
subroutine. 


The RETURN <line number> form of the RETURN statement may be 
used to return to a specific line number from the trapping subroutine. Use 
this type of return with care, however, because any other GOSUBs, 
WHILEs, or FORs that were active at the time of the trap will remain 
active, and errors such as “FOR without NEXT” may result. 


Event trapping does not take place when GW-BASIC is not executing a 


program, and event trapping is automatically disabled when an error trap 
occurs. 
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Where: <i> is an integer expressing a legal user-defined key number. 


Example: 


10 KEY 4,“SCREEN 0,0” ’assigns softkey 4 
20 KEY(4) ON ’enables event trapping 
70 ON KEY(4) GOSUB 200 


key 4 pressed 


100 Subroutine for screen 
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7.99 ON PLAY STATEMENT 
Syntax: 
ON PLAY (n) GOSUB LINE-NUMBER 


(n) is an Integer expression in the range | through 32. Values outside this 
range will result in an “Illegal function call” error. 


LINE-NUMBER is the statement line number of the Play event trap 
subroutine. 


Purpose: 


To branch to a specified subroutine when the music queue contains fewer 
than (n) notes. This permits continuous music during program execution. 


Remarks: 


ON PLAY causes an event trap when the Background Music queue goes 
from (n) notes to (n-1) notes. 


(n) must be an integer between | and 255. 


PLAY ON Enables Play event trapping 
PLAY OFF Disables Play event trapping 
PLAY STOP Suspends Play event trapping 


If a PLAY OFF statement has been executed, the GOSUB is not per- 
formed and is not remembered. 


Ifa PLAY STOP statement has been executed, the GOSUB is not per- 
formed, but will be performed as soon as a PLAY ON statement is 
executed. 


When an event trap occurs (1.e., the GOSUB is performed), an automatic 
PLAY STOP is executed so that recursive traps cannot take place. The 
RETURN from the trapping subroutine will automatically perform a 
PLAY ON statement unless an explicit PLAY OFF was performed inside 
the subroutine. 
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The RETURN <dine number> form of the RETURN statement may be 
used to return to a specific line number from the trapping subroutine. Use 
this type of return with care, however, because any other GOSUBs, 
WHILEs, or FORs that were active at the time of the trap will remain 
active, and errors such as “FOR without NEXT” may result. 


Rules: 


1. A play event trap is issued only when playing background music 
(e.g., PLAY “MB..). Play event traps are not issued when running 
in Music Foreground (e.g., default case, or PLAY “MF..). 


2. A play event trap is not issued if the background music queue has 
already gone from having (n) to (n-1) notes when a PLAY ON is 
executed. 


3. If (n) is a large number, event traps will occur frequently enough 
to diminish program execution speed. 


Also see PLAY ON, PLAY OFF, PLAY STOP Statements, Section 
7.113. 


Example: 


In this example control branches to a subroutine when the background 
music buffer decreases to 7 notes. 


100 PLAY ON 


540 PLAY ‘MB L1 XZITHER$S” 
550 ON PLAY(8) GOSUB 6000 


6000 REM **BACKGROUND MUSIC** 


6010 LET COUNT% = COUNTS% + 1 


6999 RETURN 


7-134 


Basic Commands, Functions and Statements 


7.100 ON STRIG STATEMENT 
Syntax: 

ON STRIG(n) GOSUB <line number> 
where (n) is the number of the joystick trigger. 


where <line number> is the number of the first line of a subroutine that is 
to be performed when the joystick trigger is pressed. 


Purpose: 


To specify the first line number of a subroutine to be performed when the 
joystick trigger is pressed. 


Remarks: 
A <line number> of zero disables the event trap. 


The ON STRIG statement will only be executed if a STRIG ON statement 
has been executed (see STRIG Function and STRIG Statements Sections 
7.150 and 7.151) to enable event trapping. If event trapping is enabled, and 
if the <line number> in the ON STRIG statement is not zero, GW- 
BASIC checks between statements to see if the joystick trigger has been 
pressed. If it has, a GOSUB will be performed to the specified line. 


If a STRIG OFF statement has been executed (see STRIG Statement, 
Section 7.150), the GOSUB is not performed and is not remembered. 


If a STRIG STOP statement has been executed (see STRIG Statement, 
Section 7.150), the GOSUB is not performed, but will be performed as 
soon as a STRIG ON statement is executed. 


When an event trap occurs (1.e., the GOSUB is performed), an automatic 
STRIG STOP is executed so that recursive traps cannot take place. The 
RETURN from the trapping subroutine will automatically perform a 
STRIG ON statement unless an explicit STRIG OFF was performed 
inside the subroutine. 
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The RETURN <line number> form of the RETURN statement may be > 
used to return to a specific line number from the trapping subroutine. Use 
this type of return with care, however, because any other GOSUBs, 
WHILEs, or FORs that were active at the time of the trap will remain 
active, and errors such as “FOR without NEXT” may result. 


Event trapping does not take place when GW-BASIC is not executing a 
program, and event trapping is automatically disabled when an error trap 
occurs. 


NOTE 
n may be 0, 2, 4, or 6, and indicates the 
trigger to be trapped as follows: 


0 trigger Al 
2 trigger Bl 
4 trigger A2 
6 trigger B2 
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7.101 ON TIMER STATEMENT 
Syntax: 

ON TIMER (n) GOSUB <line number> 
Purpose: 
To provide an event trap during real time. 
Remarks: 


ON TIMER causes an event trap every (n) seconds. (n) must be a numeric 
expression in the range of | to 86400 (1 second to 24 hours). Values outside 
this range generate an “I]legal function call” error. 


The ON TIMER statement will only be executed if a TIMER ON state- 
ment has been executed to enable event trapping. If event trapping is 
enabled, and if the <line number> in the ON TIMER statement is not 
zero, GW-BASIC checks between statements to see if the time has been 
reached. If it has, a GOSUB will be performed to the specified line. 


If a TIMER OFF statement has been executed, the GOSUB is not per- 
formed and is not remembered. 


If a TIMER STOP statement has been executed, the GOSUB is not 


performed, but will be performed as soon as a TIMER ON statement is 
executed. 
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When an event trap occurs (i.e., the GOSUB is performed), an automatic 
TIMER STOP is executed so that recursive traps cannot take place. The 
RETURN from the trapping subroutine will automatically perform a 
TIMER ON statement unless an explicit TIMER OFF was performed 
inside the subroutine. 


The RETURN <line number> form of the RETURN statement may be 
used to return to a specific line number from the trapping subroutine. Use 
this type of return with care, however, because any other GOSUBs, 
WHILEs, or FORs that were active at the time of the trap will remain 
active, and errors such as “FOR without NEXT” may result. 


Example: 
Display the time of day on line | every minute. 


10 ON TIMER(60) GOSUB 10000 
20 TIMER ON 


10000 LET OLDROW=CSRLIN ’Save current Row 

10010 LET OLDCOL=POS(0) ’Save current Column 

10020 LOCATE 1,1:PRINT TIMES; 

10030 LOCATE OLDROW,OLDCOL ’Restore Row & Col 
10040 RETURN 


Also see TIMER ON, TIMER OFF and TIMER STOP Statements, 
Section 7.160. 
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7.102 OPEN STATEMENT 
Syntaxes: 


OPEN <model>.,[#]<file number>, <filespec> 
[,<record length>] 


OPEN <filespec> (FOR <mode2>) AS [#]<file number> 
[LEN=<record length>] 


<filespec> is an optional device specification followed by a filename or 
pathname, that conforms to MS-DOS 2.0’s rules for filenames. 


<device> is a character device. 


<model> is a string expression. The first character must be one of the 
following: 


O Specifies sequential output mode. 

I Specifies sequential input mode. 

R Specifies random input/output mode. 

A Specifies sequential output mode and sets the file point- 


er at the end of file and the record number as the last 
record of the file. A PRINT# or WRITE# statement will 
then extend (append) the file. 


<mode2> is an expression which is one of the following: 


OUTPUT = Specifies sequential output mode. 
INPUT Specifies sequential input mode. 


APPEND _ Specifies sequential output mode and sets the file point- 
er at the end of file and the record number as the last 
record of the file. A PRINT# or WRITE# statement will 
then extend (append) the file. 


If <mode2> is omitted, the default random access mode is assumed. 
Random, however, cannot be expressed explicitly as the file mode. 
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<file number> is an integer expression whose value is between | and 255. 
The number is then associated with the file for as long as it is OPEN and 1s 
used to refer other disk I/O statements to the file. 


<record length> is an integer expression that, if included, sets the record 
length for random files. GW-BASIC 2.0 will ignore this option if it is used 
in a statement to OPEN a sequential file. The default length for records 1s 
128 bytes, unless the command line options /I and / R have been used (see 
Section 2.2, “Command Line Option Switches”). 


Purpose: 

To allow I/O to a file or device. 

Remarks: 

Files 

A file must be opened before any I/O operation can be performed on that 
file. OPEN allocates a buffer for I/O to the file or device and determines 
the mode of access that will be used with the buffer. 

OPEN allows <pathname> in place of <filespec>. If the pathname is 
used, and a drive is specified, the drive must be specified at the beginning of 


the pathname. That is, “B:\SALES\JOHN” is legal, while “\SALES\B: 
JOHN” is NOT legal. 
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The LEN= option is ignored if the file being opened has been specified as a 
sequential file. 


Since it is possible to reference the same file in a sub-directory via different 
paths, it is nearly impossible for BASIC to know that it is the same file 
simply by looking at the path. For this reason, BASIC will not let you open 
the file for OUTPUT or APPEND if it is on the same disk even if the path 
is different. For example, if MARY is your current directory, then: 


OPEN “REPORT” 

OPEN “\SALES\MARY\REPORT”... 
OPEN “..\MARY\REPORT” ... 
OPEN “..\..\WMARY\REPORT®” ... 


all refer to the same file. 
MS-DOS Devices 
BASIC devices are: 
KYBD.: LPT: 
SCRN: CONS: 
COMI: 
The BASIC file I/O system allows the user to take advantage of user 
installed devices (see the MS-DOS 2.0 manual for information on charac- 
ter devices). 
Character devices opened are opened and used in the same manner as disk 


files. However, characters are not buffered by BASIC as they are for disk 
files. The record length is set to one. 
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BASIC only sends a CR (carriage return X’GD’) as end of line. If the 
device requires a LF (line feed X’OA’), the driver must provide it. When 
writing device drivers, keep in mind that BASIC users will want to read 
and write control information. Writing and reading of device control data 
is handled by the BASIC IOCTL statement and IOCTLS§(f) function. 


NOTE 
A file can be opened for sequential 
input or random access on more than 
one file number at a time. A file may 
be OPENed for output, however, on 
only one file number at a time. 
Examples: 


10 OPEN “I”,2,“INVEN” 
10 OPEN “MAILING.DAT” FOR APPEND AS | 


If a user writes and installs a device called FOO, then the OPEN statement 
might appear as: 


10 OPEN “\DEV\FOO” FOR OUTPUT AS #1 

To open the printer for output, the user could use the line: 
100 OPEN “LPT:” FOR OUTPUT AS #1 

which uses the GW-BASIC device driver, or as part of a pathname as in: 
100 OPEN “\DEV\LPT1” FOR OUTPUT AS #1 


which uses the MS-DOS device driver. 
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7.103 OPEN COM STATEMENT 

Syntax: 
OPEN “COMn: [<speed>][,[<parity>] 
[,[<data>][,[<stop>][,RS][,CS[n]][,DS[n]] 
[,CD[n]] [,BIN] [,ASC][,LF]]]]” [FOR <mode> AS 
[#]<file number> [LEN= <record length>] 

COMn: is the name of the device to be opened. 


nis the number or a legal communications device, i.e., COM1: or COM2:. 


<speed> is the baud rate, in bits per second, of the device to be opened 
(75, 150, 300, 600, 1200, 2400, 4800 and 9600). 


<parity> designates the parity of the device to be opened. Valid entries 
are: N (none), E (even), O (odd). 


<data> designates the number of data bits per byte. Valid entries are: 5, 6, 
7, or 8. 


<stop> designates the stop bit. Valid entries are: 1, 1.5, or 2. 
RS suppresses RTS (Request To Send). 

CS[n] controls CTS (Clear To Send). 

DS[n] controls DSR (Data Set Ready). 

CD[n] controls CD (Carrier Detect). 


LF specifies that a linefeed is to be sent after a carriage return. See 
“Remarks” for further discussion of LF. 


BIN opens the device in binary mode. BIN is selected by default unless 
ASC 1s specified. See “Remarks” for further discussion of BIN. 


ASC opens the device in ASCII mode. See “Remarks” for further discus- 
sion of ASC. 


7-143 


Basic Commands, Functions and Statements 


<mode> is one of the following string expressions: 


OUTPUT = Specifies sequential output mode. 
INPUT Specifies sequential input mode. 


If the <mode> expression is omitted, it is assumed to be random 
input/output. Random cannot, however, be explicitly chosen as <mode>. 


<file number> is the number of the file to be opened. 

Purpose: 

To open and initialize a communications channel for input/output. 
Remarks: 


The OPEN COM statement must be executed before a device can be used 
for RS232 communication. 


Any syntax errors in the OPEN COM statement will result in a “Bad File 
name” error. 


The <speed>, <parity>,<data>, and <stop> options must be listed in 
the order shown in the above syntax. The remaining options may be listed 
in any order, but they must be listed after the <speed>, <parity>, 
<data>, and <stop> options. 


A “Device timeout” error will occur if Data Set Ready (DSR) is not 
detected. 


LF allows communication files to be printed ona serial line printer. When 
LF 1s specified, a linefeed character (OAH) is automatically sent after each 
carriage return character (OCH). This includes the carriage return sent as 
a result of the width setting. Note that INPUT# and LINE INPUT#, when 
used to read from a COM file that was opened with the LF option, stop 
when they see a carriage return, ignoring the linefeed. 
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The LF option is superseded by the BIN option. 


In the BIN mode, tabs are not expanded to spaces, a carriage return Is not 
forced at the end-of-line, and Control-Z is not treated as end-of-file. When 
the channel is closed, Control-Z will not be sent over the RS232 line. The 
BIN option supersedes the LF option. 


In ASC mode, tabs are expanded, carriage returns are forced at the 
end-of-line, Control-Z is treated as end-of-file, and XON/ XOFF protocol 
(if supported) is enabled. When the channel is closed, Control-Z will be 
sent over the RS232 line. 


Example: 

10 OPEN “COM1:9600,N,8,1,GIN” AS #2 
will open communications channel | in random mode at a speed of 9600 
baud with no parity bit, 8 data bits, and | stop bit. Input/Output will be in 


the binary mode. Other lines in the program may now access channel | as 
file number 2. 
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7.104 OPTION BASE STATEMENT 
Syntax: 
OPTION BASE n 
where nis | or 0. 
Purpose: 
To declare the minimum value for array subscripts. 
Remarks: 
The default base is 0. If the statement 
OPTION BASE 1 
is executed, the lowest value an array subscript may have is 1. 


The OPTION BASE statement must be coded before you define or use any 
arrays. 


Chained programs may have an OPTION BASE statement if no arrays are 
passed between them or the specified base is identical in the chained 
programs. The chained program will inherit the OPTION BASE value of 
the chaining program. 


Example: 


10 OPTION BASE | 
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7.105 OUT STATEMENT 
Syntax: 
P OUT I,J 


where I is the port number. It must be an integer expression in the range 0 
to 65535. 


J is the data to be transmitted. It must be an integer expression in the range 
0 to 255. 


Purpose: 
To send a byte to a machine output port. 
Example: 
100 OUT 12345,255 
¢ In 8086 assembly language, this is equivalent to: 
MOV DX, 12345 


MOV AL,255 
OUT DX,AL 
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7.106 PAINT STATEMENT 
Syntax: 


PAINT (<x>,<y>)[,<paint attribute> 
[,<border color>][,background attribute]] 


(<xstart> and <ystart>) are the coordinates where painting is to begin. 
Painting should always start on a non-border point. If painting starts 
within a border, the bordered figure is painted. If painting starts outside a 
bordered figure, the background is painted. 


If the <paint attribute> is a string expression PAINT will execute 
“Tiling,” a process similar to “Line-styling.” Like LINE, PAINT looks at 
a “tiling” mask each time a point is put down on the screen. 


If <paint attribute> is a numeric expression, then the number must be a 
valid color and is used to paint the area as before (see COLOR Statement, 
Section 7.20). If the <paint attribute> is not specified, the foreground 
color will be used. 


<border color> identifies the border color of the figure to be filled. When 
the order color is encountered, painting of the current line will stop. If the 
<border color> is not specified, the <paint attribute> will be used. 


<background attribute> is a string formula returning character data. 
When it is omitted, the default is CHRS$(0). 


When specified, <background attribute> gives the “background tile 
slice” to skip when checking for termination of the boundary. Painting is 
terminated when adjacent points display the paint color; specifying a 
background tile slice allows the user to paint over an already painted area 
without terminating the process because two consecutive lines with the 
Same paint attributes are encountered. 


Purpose: 


To fill a graphics area with the color or pattern specified. 
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Remarks: 


Painting is complete when a line is painted without changing the color of 
any pixel; i.e., the entire line is equal to the paint color. 


The PAINT command can be used to fill any figure, but painting complex 
figures may result in an “Out of Memory” error. If this happens, the 
CLEAR statement may be given to increase the amount of stack space 
available. 


The PAINT command permits coordinates outside the screen or viewport. 
Tiling 


Tiling is the design of a PAINT pattern that is 3 bits wide and up to 64 
bytes long. Each byte in the Tile String masks 8 bits along the x axis when 
putting down points. Construction of this Tile mask works as follows: 


Use the syntax PAINT (x,y), CHR$(n)...CHRS$(n) where (n) is a number 
between 0 and 255 which will be represented in binary across the x-axis of 
the “tile”. Each CHR§(n) up to 64 will generate an image not of the 
assigned character, but of the bit arrangement of the code for that charac- 
ter. For example, the decimal number 85 is binary “01010101”; the graphic 
image line on a black and white screen generated by CHR§(85) is an eight 
pixel line, with even numbered points turned white, and odd ones black. 
That is, each bit containing a “1” will set the associated pixel on and each 
bit filled with a “0” will set the associated bit off in a black and white 
system. The ASCII character CHR$(85), which is “U,” is not displayed in 
this case. 


If the current screen mode supports only two colors, then the screen can be 
painted with ’X’s with the following statement. 


PAINT (320,100),CHR$(129)+CHR$(66) 


+CHR$(36)+CHR§$(24)+ CHR$(24)+CH R$(36)+ 
CHR$(66)+CHR§(129) 
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This appears on the screen as: 


x Increases 


0,00 x x CHR$(129) Tile byte | 
0,1 x X CHR$(66) Tile byte 2 
0,2 * X CHR$(36) ‘Tile byte 3 
0,3 x xX CHR§$(24) Tile byte 4 
0,4 x x CHR§(24) _ Tile byte 5 
0,5 X X CHR$(36) ‘Tile byte 6 
0,6 X X CHR$(66) Tile byte 7 
0,7 x x CHR§( (129) Tile byte 8 


In four-color graphics mode which is selected palette-0 or palette-1 in the 
COLOR statement, one tile byte describes four pixels. Entry two bits of 
the tile byte describes one of four possible color associated with each of the 
four pixels to be plotted. 


The following chart shows the binary and hexadecimal values associated 
with the given colors. 


PATTERN PATTERN 

COLOR | TO DRAW TO DRAW 
SOLID SOLID 
IN LINE IN LINE IN 


BINARY | BINARY |HEXADECIMAL 


01010101 
magenta 10101010 
white 11111111 
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The following example plots a pattern of boxes with a border color of red 
in palette 0 and magenta in palette 1. 


PAINT (320,100), CHRS(&HAA)+CHRS(&H82)+CHRS(&H82) 
+CHRS(&H82)+CHRS(&H82)+CHRS(&H82)+CHRS(&H8s) 
+CHRS(&HAA) 


76543210 
Tile byteO 101010410 CHRS(&HAA) 
Tile byte! 10000010 CHRS(&H82) 
Tile bytte2 10000010 CHRS(&H82) 
Tile byte3 10000010 CHRS(&H82) 
Tile byte4 10000010 CHRS(&H82) 
Tile bytteS5 10000010 CHRS(&H82) 
Tile byte6 10000010 CHRS(&H82) 
Tile byte7 101010410 CHRS(&HAA) 


In eight-color graphics mode which is selected palette-2 in the COLOR 
statement, one tile byte describes only two pixels. Every four bits of the tile 
byte describes one of eight possible colors associated with each of the two 
pixels to be plotted. 


The following chart shows the binary and hexadecimal values associated 
with the given color. 
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PATTERN PATTERN 
TO DRAW TO DRAW 
SOLID SOLID 
LINE IN LINE IN 
BINARY HEXADECIMAL 


00100010 


01000100 

01100110 

10001000 

Magenta 10101010 
Yellow 11001100 
White 11101110 





When supplied, <background attr> specifies the “background tile slice” 
to skip when checking for boundary termination. 


You cannot specify more than two consecutive bytes in the tile back- 
ground slice that match the tile string. Specifying more than two will result 
in an “Illegal function call” error. 
Example: 

10 PAINT (5,15),2,0 


begins painting at coordinates 5,15 with color 2 and border color 0, and 
fills to a border. 
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7.107 PALETTE, PALETTE USING STATEMENTS 
Syntax: 


PALETTE [<color number>,<display color>] 
or 
PALETTE USING <array> (<array index>) 


<color number> is one of the color numbers that may be used in a 
GW-BASIC statement. The range of <color number> is 0 to 7. 


<display color number> is an integer representing one of the colors that is 
possible to create on the display screen. The range of <display color 
number> is 0 to 7. 


<array> is the name of an integer array. 

<array index> specifies the index of the first array element to use. 
Purpose: 

To change one or more of the colors in the palette. 

Remarks: 


The palette is essentially a map specifying how color numbers used in 
GW-BASIC statements are mapped to colors on the display screen. 


The parameter <color number> specifies any of the possible colors that 
may be used in any of the graphics statements. The color number might 
also be used in the COLOR statement to set the default text color. 


The <display color number> parameter specifies the way that graphic 
points (or text characters) colored with the color number will appear on 
the display screen. Under a common initial palette setting, points colored 
with color number 0 will appear as black on the display screen. Using the 
PALETTE statement, the user may change the mapping of color number 0 
to display color white. 


If the optional parameters are not specified, this statement sets the palette 
to a known initial setting. This setting is the same as the setting when 
GW-BASIC is first initiated. 
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If the USING option is specified, each entry in the palette may be modified 
at once. GW-BASIC will set each color number in the palette to the 
respective display color in the array. 


If <display color number> or an array entry is -1 then the mapping for 
the associated color number is not changed. Other negative numbers are 
illegal values for <display color number>. 


If the options are specified, the color specified by <palette number> 1s 
changed to the color specified by <color number>. For example, assume 
that the current palette consists of display colors 0, 1, 2, and 3. The 
statement PALETTE 3,2 will result in a new palette of display colors 0, 1, 
2, and 2. 


Example: 
PALETTE 0,2 
changes all points colored with color number 0 to display color 2. 
PALETTE 0.-1 
does not modify the palette. 
PALETTE A%(0) 
changes each palette entry. All color numbers will now be mapped to 
display color zero (since the array will be initialized to zero by GW-BASIC 
when it is first declared). The screen will appear as one single color. 
However, it will still be possible to enter GW-BASIC statements. For 
instance: 


PALETTE 


sets each palette entry to the appropriate initial display color. The screen 
will no longer appear as one single color. 
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7.108 PEEK FUNCTION 
Syntax: 

PEEK(I) 
Purpose: 
To return the byte read from the indicated memory location (1). 
Remarks: 
The returned value is an integer in the range 0 to 255. I must be in the range 
-32768 to 65535. Lis the offset from the current segment, which was defined 
by the last DEF SEG statement (see Section 7.32). For the interpretation 
of a negative value of I, see VARPTR Function, Section 7.164. 
PEEK is the complementary function of the POKE statement. 
Example: 

A=PEEK(&HS5AOO) 


In this example, the value at the location with the hex address SAOO is 
loaded into a variable A. 


7-155 


Basic Commands, Functions and Statements 


7.109 PEN ON, PEN OFF, PEN STOP STATEMENTS 
Syntax: 


PEN ON 
PEN OFF 
PEN STOP 


Purpose: 


The PEN ON statement enables the lightpen read function and event 
trapping. 


The PEN OFF statement disables the lightpen read function and event 
trapping. 

The PEN STOP statement disables the lightpen read function and event 
trapping but remembers a PEN event so that it can be trapped as soon as 
event trapping is enabled. 

Remarks: 

The pen is initially off. A PEN ON statement must be executed before any 
pen read function calls (see PEN Function, Section 7.110) can be made. If 
the function is called when the pen is off, an “Illegal function call” error 


will result. 


PEN ON also enables event trapping by an ON PEN statement. Fora full 
discussion of pen event trapping, see ON PEN Statement, Section 7.98. 


On some machines, the pen should not be used in the border area of the 
screen. Any values returned while the pen is in that area will be inaccurate. 


To speed program execution, the pen should be turned off with a PEN 
OFF statement for programs not using the lightpen. 


Example 1: 
10 PEN ON ‘enables lightpen read function and event trap 
Example 2: 


20 PEN OFF ‘disables lightpen read function and event trap 
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7.110 PEN FUNCTION 
Syntax: 
PEN(n) 


(n) is anumeric expression returning an unsigned integer in the range 0 to9 
(see below). 


The x = PEN(n) function reads the light pen coordinates, where n 1s: 


0 — If pen was down since last poll. Returns -1 if down, 0 if not. 
1 — Returns the x pixel coordinate where pen was last pressed. 
2 — Returns the y pixel coordinate where pen was last pressed. 


3 — Returns the current pen switch value: -1 (true) if down, 0 if up. 
Also stores the value for PEN(4), PEN(5), PEN(8), and PEN(9) 
if pen was pressed. 


4 — Returns the x pixel coordinate where last PEN(3) was true. 


5 — Returns the last known valid y pixel coordinate where last 
PEN(3) was true. 


6 — Returns the character row position where pen was last pressed. 


7 — Returns the character column position where pen was last 
pressed. 


8 — Returns the last row where last PEN(3) was true. 


9 — Returns the column where last PEN(3) was true. 
Example: 


5 CLS 
10 PEN ON 
20 P=PEN(3) 
30 LOCATE 1,1: PRINT “PEN IS”: 
40 IF P THEN PRINT “DOWN” ELSE PRINT “UP” 
50 GOTO 20 


This example produces an endless loop to print the current pen switch 
status (UP/ DOWN). 
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7.111 PLAY STATEMENT 
Syntax: 
PLAY <string> 
<string> is one or more of the subcommands listed under “Remarks.” 
Purpose: 


To play music as specified by <string>. Requires optional joystick and 
sound board. 


Remarks: 

PLAY uses a concept similar to that in DRAW (see Section 7.36) by 
embedding a Music Macro language into one statement. A set of sub- 
commands, used as part of the PLAY statement, specifies the particular 


action to be taken. 


Prefixes-ChangeOctave 


> Increments octave. Octave will not advance beyond 6. 
< Decrements octave. Octave will not drop below 0. 

Tone 

0 <n> Sets the current octave. There are seven octaves, num- 


bered 0 through 6. 


A-G Plays a note in the range A-G. # or + after the note 
specifies sharp; — specifies flat. 


N <n> Plays note n. n may range from 0 through 84 (in the 7 
possible octaves, there are 84 notes). n = 0 means a rest. 
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Duration 

L <n> Sets the length of each note. L 4is a quarter note, L lisa 
whole note, etc. n may be in the range | through 64. 
The length may also follow the note when a change of 
length only is desired for a particular note. In this case, A 
16 is equivalent to L 16 A. 

MN Sets “music normal” so that each note will play % of the 
time determined by the length (L). 

ML | Sets “music legato” so that each note will play the full 
period set by length (L). 

MS Sets “music staccato” so that each note will play % of the 
time determined by the length (L). 

Tempo 

P <n> Specifies a pause, ranging from | through 64. This option 
corresponds to the length of each note, set with L <n>. 

T <n> Sets the “tempo,” or the number of L 4’s in one minute. n 
may range from 32 through 255. The default is 120. 

Operation 

MF Sets music (PLAY statement) and SOUND to run in the 
foreground. That is, each subsequent note or sound will 
not start until the previous note or sound has finished. 
This is the default setting. 

MB Music (PLAY statement) and SOUND are set to run in 


the background. That is, each note or sound is placed ina 
buffer allowing the GW-BASIC program to continue 
executing while the note or sound plays in the back- 
ground. The number of notes that can be played in the 
background at one time varies according to the particular 
machine. 
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Substring 


X <string> 


Suffixes 


= ort 


Examples: 


Executes a substring. Because of the slow clock interrupt 
rate, some notes will not play at higher tempos (L 64 at T 
255, for example). 


Note (as shown in the “Examples” below) that a substring 
may be executed by appending the character form of the 
substring address to “X”. 


Follows a specified note, and turns it into a sharp. 
Follows a specified note, and turns it into a flat. 


A period after a note causes the note to play 3/2 times the 
length determined by L multiplied by T (tempo). Multi- 
ple periods may appear after a note. The period is scaled 
accordingly; for example, A. is 3/2, A.. is 9/4, A... is 
27/8, etc. Periods may appear after a pause (P). In this 
case, the pause length may be scaled in the same way 
notes are scaled. 


PLAY “<<” Decrement by two octaves 
PLAY “>” Increment by an octave 


PLAY “>A” Increment by an octave and play an A note 
PLAY “XSONG$” 


LET LISTEN$ = “T180 02 P2 P8 L8 GGG L2 E-” 
LET FATE$ = “P24 P8 L8 FFF L2 D” 
PLAY LISTENS + FATE$ 


This example will play the beginning of the first movement of Beethoven’s 
Fifth Symphony. 
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7.112 PLAY FUNCTION 
Syntax: 
PLAY (n) 
(n) is a dummy argument and may be any value. 
Purpose: 
To return the number of notes currently in the background music queue. 
Remarks: 


PLAY(n) will return 0 when the user is in Music Foreground Mode. 
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7.113 PLAY ON, PLAY OFF, PLAY STOP STATEMENTS 
Syntax: 


PLAY ON 
PLAY OFF 
PLAY STOP 


Purpose: 


PLAY ON enables play event trapping. PLAY OFF disables play event 
trapping. PLAY STOP suspends play event trapping. 


Remarks: 


Ifa PLAY OFF statement has been executed the GOS UB 1s not performed 
and is not remembered. 


If a PLAY STOP statement has been executed the GOSUB is not per- 
formed, but will be performed as soon as a PLAY ON statement 1s 
executed. 


When an event trap occurs (i.e., the GOS UB is performed), an automatic 
PLAY STOP is executed so that recursive traps cannot take place. The 
RETURN from the trapping subroutine will automatically perform a 
PLAY ON statement unless an explicit PLAY OFF was performed inside 
the subroutine. 


The RETURN <line number> form of the RETURN statement may be 
used to return to a specific line number from the trapping subroutine. Use 
this type of return with care, however, because any other GOSUBs, 
WHILEs, or FORs that were active at the time of the trap will remain 
active, and errors such as “FOR without NEXT” may result. 
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7.114 PMAP FUNCTION 
Syntax: 

PMAP <expression>, <function> 
Purpose: 


To map world coordinate expressions to physical locations or to map 
physical expressions to a world coordinate location. 


<function> = 

0 Maps world expression to physical x coordinate. 
| Maps world expression to physical y coordinate. 
2 Maps physical expression to world x coordinate. 
3 Maps physical expression to world y coordinate. 


Remarks: 
The four PMAP functions allow the user to find equivalent point locations 
between the world coordinates created with the WINDOW statement and 


the physical coordinate system of the screen or viewport as defined by the 
VIEW statement. 
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Examples: 
If a user had defined a WINDOW SCREEN (80,100) - (200,200) then the 
upper left coordinate of the window would be (80,100) and the lower right 
would be (200,200). The screen coordinates may be (0,0) in the upper left 
hand corner and (639,199) in the lower right. Then: 
X = PMAP(80,0) 
would return the screen x coordinate of the window x coordinate 80: 
0 
The PMAP function in the statement: 
Y = PMAP(200,1) 
would return the screen y coordinate of the window y coordinate 200: 
199 
The PMAP function in the statement: 


X = PMAP(619,2) 


would return the “world” x coordinate that corresponds to the screen or 
viewport x coordinate 619: 


199 
The PMAP function in the statement: 
Y = PMAP(100,3) 


would return the “world” y coordinate that corresponds to the screen or 
viewport y coordinate 100: 


140 
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7.115 POINT FUNCTION 
Syntax: 
POINT (<xcoordinate>,<ycoordinate>) 


<xcoordinate> and <ycoordinate> are the coordinates of the pixel that 
is to be referenced. 


Or 
POINT (<function>) 
Purpose: 


POINT (x,y) allows the user to read the color number of a pixel from the 
screen. If the specified point is out of range, the value -1 is returned. 


POINT with one argument allows the user to retrieve the current Graphics 
cursor coordinates. Therefore: 


x= POINT(FUNCTION) 
Returns the value of the current x or y. Graphics accumulator as follows: 


function = 
0 Returns the current physical x coordinate. 
| Returns the current physical y coordinate. 


2 Returns the current logical x coordinate. If the WINDOW state- 
ment has not been used, this will return the same value as the 
POINT(0O) function. 


3 Returns the current logical y coordinate if WINDOW 1s active, else 
returns the current physical y coordinate as in | above. 


where the physical coordinate is the coordinate on the screen or current 
viewport. 
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Examples: 


10 SCREEN | 

20 LET C=3 

30 PSET (10,10),C 

40 IF POINT(10,10)=C THEN PRINT “This point is color ”;C 


5 SCREEN 2 
10 IF POINT(i,1)<>0 THEN PRESET (i,1) ELSE PSET (1,1) 


"Invert current state of a point 
20 PSET (i,1), 1-POINT(i,1) "another way to invert a point if the system 


is black and white. 
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7.116 POKE STATEMENT 
Syntax: 

POKE 1,J 
where I and J are integer expressions. 
Purpose: 
To write a byte into a memory location. 
Remarks: 


I and J are integer expressions. The expression I represents the address of 
the memory location and J is the data byte. J must be in the range 0 to 255. 


I must be in the range -32768 to 65535. | is the offset from the current 
segment, which was set by the last DEF SEG statement (see Section 7.32). 
For interpretation of negative values of I1,see VARPTR Function, Section 
7.164. 


The complementary function to POKE is PEEK. (See Section 7.108.) 


WARNING 
Use POKE carefully. If it is used 
incorrectly, it can cause GW-BASIC 
or MS-DOS to crash. 
Example: 


10 POKE &H5A00,&HFF 
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7.117 POS FUNCTION 
Syntax: 

POS(I) 
Purpose: 
To return the current horizontal (column) position of the cursor. 
Remarks: 
The leftmost position is |. 1isa dummy argument. To return the current 
vertical line position of the cursor, use the CSRLIN function (Section 
T.20). 
Example: 


IF POS(X)>60 THEN BEEP 


Also see LPOS Function, Section 7.83. 
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7.118 PRESET STATEMENT 


Syntax: 


PRESET [STEP](<xcoordinate>,<ycoordinate>) [,<color>] 
<xcoordinate> and <ycoordinate> specify the pixel that 1s to be set. 
<color> is the color number that is to be used for the specified point. 


The STEP option, when used, indicates the given x and y coordinates will 
be relative, not absolute. That means the x and y are distances from the 
most recent cursor location, not distances from the (0,0) screen coordinate. 


Purpose: 


To draw a specified point on the screen. PRESET works exactly like 
PSET except that if the <color> is not specified, the background color is 
selected. 


Remarks: 


If a coordinate is outside the current viewport, no action is taken, nor is an 
error message given. 


Coordinates can be shown as absolutes, as in the above syntax, or the 
STEP option can be used to reference a point relative to the most recent 
point used. For example, if the most recent point referenced were (10,10), 
STEP (10,5) would reference the point at (20,15). 


Example: 


5 REM DRAW A LINE FROM (0,0) TO (100,100) 
10 FOR i=0 TO 100 
20 PRESET (i,i), 1 
30 NEXT 
35 REM NOW ERASE THAT LINE 
40 FOR i=0 TO 100 
50 PRESET STEP (-1,-1) 
60 NEXT 


This example draws a line from (0,0) to (100,100) and then erases that line 
by overwriting it with the background color. 
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7.119 PRINT STATEMENT 
Syntax: 

PRINT [<list of expressions>] 
Purpose: 
To output data on the screen. 
Remarks: 


If <list of expressions> is omitted, a blank line is printed. If <list of 
expressions> is included, the values of the expressions are printed on the 
screen. The expressions in the list may be numeric and/or string expres- 
sions. (String literals must be enclosed in quotation marks.) 


A question mark (?) can be used as a form of shorthand by the user. It will 
be interpreted as the word “PRINT”, and will appear as “PRINT” in 
subsequent listings. 


Print Positions 


The position of each printed item is determined by the punctuation used to 
separate the items in the list. Microsoft GW-BASIC divides the line into 
print zones of 14 spaces each. In the list of expressions, acomma causes the 
next value to be printed at the beginning of the next zone. A semicolon 
causes the next value to be printed immediately after the last value. Typing 
One or more spaces between expressions has the same effect as typing a 
semicolon. 


If a comma or a semicolon terminates the list of expressions, the next 
PRINT statement begins printing on the same line, spacing according to 
instructions. If the list of expressions terminates without a comma or a 
semicolon, a carriage return is printed at the end of the line. If the printed 
line is wider than the screen width, Microsoft GW-BASIC goes to the next 
physical line and continues printing. 
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Printed numbers are always followed by a space. Positive numbers are pre- 
ceded by a space. Negative numbers are preceded by a minus sign. Single 
precision numbers that can be represented with 6 or fewer digits in the un- 
scaled format no less accurately than they can be represented in the scaled 
format are output using the unscaled format. For example, 1 E-7 is output as 
.0000001 and 1E-8 is output as 1E-08. Double precision numbers that can 
be represented with 16 or fewer digits in the unscaled format no less accu- 
rately than they can be represented in the scaled format are output using 
the unscaled format. For example, | D-15 is output as .000000000000000 1 
and 1D-16 is output as 1D-16. 


With the interpreter, a question mark may be used in place of the word 
PRINT in a PRINT statement. 


Example 1: 


10 X=5 

20 PRINT X+5,X-5,X*(-5),X ~ 5 
30 END 

will yield 

10 0 -25 3125 


In this example, the commas in the PRINT statement cause each value to 
be printed at the beginning of the next print zone. 


Example 2: 


10 INPUT X 

20 PRINT X “SQUARED IS” XK * 2 “AND”; 
30 PRINT X “CUBED IS” X * 3 

40 PRINT 

50 GOTO 10 


will yield 
29 
9 SQUARED IS 81 AND 9 CUBED IS 729 


ar | 
21 SQUARED IS 441 AND 21 CUBED IS 9261 
? 
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In this example, the semicolon at the end of line 20 causes both PRINT 
statements to be printed on the same line. Line 40 causes a blank line to be 
printed before the next prompt. 


Example 3: 


10 FOR X=1 TO 5 
20 J=J+5 

30 K=K+10 

40 ?J;K; 

50 NEXT X 


will yield 
5 10 10 20 15 30 20 40 25 50 
In this example, the semicolons in the PRINT statement cause each value 
to be printed immediately after the preceding value. (Remember, a 


number is always followed by a space, and positive numbers are preceded 
by a space.) In line 40, a question mark is used instead of the word PRINT. 


7-172 


Basic Commands, Functions and Statements 


7.120 PRINT USING STATEMENT 
Syntax: 

PRINT USING <string exp>;<list of expressions> 
Purpose: 
To print strings or numbers using a specified format. 
Remarks/ Examples: 


<list of expressions> is comprised of the string expressions or numeric 
expressions that are to be printed, separated by semicolons. 


<string exp> is a String literal (or variable) composed of special format- 
ting characters. These formatting characters (see below) determine the 
field and the format of the printed strings or numbers. 


String Fields 


When PRINT USING 1s used to print strings, one of three formatting 
characters may be used to format the string field: 


66999 
! 


Specifies that only the first character in the given string 1s 
to be printed. 
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“\n spaces\” Specifies that 2 + n characters from the string are to be 
printed. If the backslashes are typed with no spaces, two 
characters will be printed; with one space, three characters 
will be printed, and so on. If the string is longer than the a’ 
field, the extra characters are ignored. If the field is longer od 
than the string, the string will be left-justified in the field 
and padded with spaces on the right. 


Example: 


10 A$=“LOOK”: B$=“OUT” 

30 PRINT USING “!”;A$;B$ 

40 PRINT USING “\ \”;A$;B$ 

50 PRINT USING “\ \”;A4;B$;“!!” 
will yield 


LO 
LOOKOUT 
LOOK OUT !! 


*&“ Specifies a variable length string field. When the field is ‘ 
specified with “&”, the string is output without modifica- y 
tion. 


Example: 


10 A$=“LOOK”: B$=“OUT” 
20 PRINT USING “!”;A$; 
30 PRINT USING “&”;B$ 


will yield 
LOUT 
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When PRINT USING is used to print numbers, the following special 
characters may be used to format the numeric field: 


#f 


A number sign is used to represent each digit position. 
Digit positions are always filled. If the number to be 
printed has fewer digits than positions specified, the 
number will be right-justified (preceded by spaces) in the 
field. 


A decimal point may be inserted at any position in the 
field. If the format string specifies that a digit 1s to precede 
the decimal point, the digit will always be printed (as 0, if 
necessary). Numbers are rounded as necessary. 


PRINT USING “##.##”:.78 
0.78 


PRINT USING “###.##";987.654 
987.65 


PRINT USING “##.## ”-10.2.5.3,66.789,.234 
10.20 5.30 66.79 0.23 


In the last example, three spaces were inserted at the end of 
the format string to separate the printed values on the line. 


A plus sign at the beginning or end of the format string will 


cause the sign of the number (plus or minus) to be printed 
before or after the number. 
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String expressions must be separated by semicolons in the list. To format 
the string expressions correctly in the file, use explicit delimiters in the list 
of expressions. — 
For example, let A$=“CAMERA” and B$=“93604-1”. The statement 
PRINT#1,A$;B$ 
would write CAMERA93604-1 to the file. Because there are no delimiters, 
this could not be input as two separate strings. To correct the problem, 
insert explicit delimiters into the PRINT# statement as follows: 
PRINT#1,A$;“,”;B$ 
The image written to the file is 
CA MERA,93604-1 
which can be read back into two string variables. 
If the strings themselves contain commas, semicolons, significant leading 


blanks, carriage returns or linefeeds, write them to the file surrounded by 
explicit quotation marks, CHR$(34). 
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For example, let A=S“CAMERA, AUTOMATIC” and B$=" 93604-1”. 
The statement 


PRINT#1,A$;B$ 
would write the following image to file: 
CAMERA, AUTOMATIC 93604-1 
And the statement 
INPUT#1,A$,B$ 
would input “CAMERA” to A$ and “AUTOMATIC 93604-1” to B$. To 
separate these strings properly in the file, write double quotation marks to 


the file image using CHR§$(34). The statement 


PRINT#1,CHR$(34);A$;CHR$(34);CHR$(34); BS 
;CHR$(34) 


writes the following image to the file: 
“CAMERA, AUTOMATIC”* 93604-1” 
And the statement 
INPUT#1,A$,B$ 
would input “CAMERA, AUTOMATIC” to A$ and “ 93604-1” to BS. 


The PRINT# statement may also be used with the USING option to 
control the format of the file. For example: 


PRINT#1,USING“SS###.##, 3S; K3L 


NOTE 


See also WRITE# Statement, Section 
T1735. 
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7.121 PRINT# AND PRINT# USING STATEMENTS 
Syntax: 


PRINT#<file number>,[USING <string exp>;] 
<list of expressions> 


Purpose: 

To write data to a sequential file. 

Remarks/ Examples: 

<file number> is the number used when the file was opened for output. 
<string exp> consists of formatting characters as described in “PRINT 
USING Statement,” Section 7.127. The expressions in <list of expres- 


sions> are the numeric and/or string expressions that will be written to 
the file. 


PRINT# does not compress data. An image of the data is written to the 
file, just as it would be displayed on the terminal screen with a PRINT 
statement. For this reason, care should be taken to delimit the data, so that 
it will be input correctly. 


In the list of expressions, numeric expressions should be delimited by 
semicolons. For example: 


PRINT#1,A;B;C;X; Y;Z 


(If commas are used as delimiters, the extra blanks that are inserted 
between print fields will also be written to the file.) 
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A minus sign at the end of the format field will cause 
negative numbers to be printed with a trailing minus sign. 


PRINT USING “+##.## ”;-68.95,2.4,55.6,-.9 
-—68.95 +2.40 +55.60 -0.90 


PRINT USING “##.##-  ”;-68.95,22.449,-7.01 
68.95— 22.45 7.01- 


A double asterisk at the beginning of the format string 
causes leading spaces in the numeric field to be filled with 
asterisks. The ** also specifies positions for two more 
digits. 


PRINT USING “**#.4  ”312.39,-0.9,765.1 
*12.4 *-0.9 765.1 


A double dollar sign causes a dollar sign to be printed to 
the immediate left of the formatted number. The $$ speci- 
fies two more digit positions, one of which is the dollar 
sign. The exponential format cannot be used with $$. 
Negative numbers cannot be used unless the minus sign 
trails to the right. 


PRINT USING “S$S###.4##"3456.78 
$456.78 


The **$ at the beginning of a format string combines the 
effects of the above two symbols. Leading spaces will be 
asterisk-filled and a dollar sign will be printed before the 
number. **§$ specifies three more digit positions, one of 
which is the dollar sign. 


The exponential format cannot be used with **$. When 
negative numbers are printed, the minus sign will appear 
immediately to the left of the dollar sign. 


PRINT USING “**$##.##";2.34 
#**$2.34 
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AANA 


A comma that is to the left of the decimal point in a 
formatting string causes a comma to be printed to the left 
of every third digit to the left of the decimal point. A 
comma that is at the end of the format string is printed as 
part of the string. A comma specifies another digit posi- 
tion. The comma has no effect if used with exponential 
(44°%) format. 


PRINT USING “####, #4"; 1234.5 
1,234.50 


PRINT USING “####.##,”;1234.5 
1234.50, 


Four carets (or up-arrows) may be placed after the digit 
position characters to specify exponential format. The 
four carets allow space for E+xx to be printed. Any 
decimal point position may be specified. The significant 
digits are left-justified, and the exponent is adjusted. 
Unless a leading + or trailing + or — 1s specified, one digit 
position will be used to the left of the decimal point to print 
a space or a minus sign. 


PRINT USING “##.#AASA*”: 234.56 
2.35D+02 


PRINT USING “.###AAA*~“~—”:-888888 
—.8839E+06 


PRINT USING “+.4#0°°°”: 123 
+, 12E+03 


An underscore in the format string causes the next charac- 
ter to be output as a literal character. 


PRINT USING “_!##. #415 12.34 
112.34! 


The literal character itself may be an underscore by placing 
“__” in the format string. 
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If the number to be printed is larger than the specified 
numeric field, a percent sign is printed in front of the 
number. If rounding causes the number to exceed the field, 
a percent sign will be printed in front of the rounded 
number. 


PRINT USING “##.4##"3111.22 
%111.22 


PRINT USING “.##”;.999 
%1.00 


If the number of digits specified exceeds 24, an ee 
function call” error will result. 
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7.122 PSET STATEMENT 
Syntax: 


PSET [STEP](<xcoordinate>,<ycoordinate>) 
[,<color>] 


(<xcoordinate> and <ycoordinate> specify the point on the screen to be 
colored. 


<color> is the number of the color to be used. 

The STEP option, when used, indicates the given x and y coordinates will 
be relative, not absolute. That means the x and y are distances from the 
most recent cursor location, not distances from the (0,0) screen coordinate. 
Purpose: 

To draw a specified point on the screen. 

Remarks: 

When GW-BASIC scans coordinate values, it will allow them to be 
beyond the edge of the screen (size of the screen is dependent on the 
particular machine being used, and can be adjusted with the WIDTH 
statement). However, values outside the integer range -32768 to 32767 will 
cause an “Overflow” error. 

Coordinates can be shown as offsets by using the STEP option to reference 
a point relative to the most recent point used. The syntax of the STEP 
option Is: 


STEP (<xoffset>,<yoffset>) 


For example, if the most recent point referenced were (0,0), PSET STEP 
(10,0) would reference a point at offset 10 from x and offset 0 from y. 
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The coordinate (0,0) is always the upper left corner of the screen. 


PSET allows the <color> to be left off the command line. If it is omitted, 
the default is the foreground color. 


Example: 


5 REM DRAW A LINE FROM (0,0) TO (100,100) 
10 FOR I=0 TO 100 
20 PSET (1,1) 
30 NEXT I 


35 REM NOW ERASE THAT LINE 
40 FOR I=0 TO 100 

50 PSET STEP (-1,-1),0 

60 NEXT | 


This example draws a line from (0,0) to (100,100) and then erases that line 
by writing over it with the background color. 
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7.123 PUT STATEMENT — FILE I/O 
Syntax: 
PUT [#]<file number>[,<record number>] 
Purpose: 
To write a record from a random buffer to a random access file. 
Remarks: 


<file number> is the number under which the file was opened. If <record 
number> is omitted, the record will assume the next available record 
number (after the last PUT or GET). The largest possible record number is 
16,777,215. The smallest record number 1s |. 


The GET and PUT statements allow fixed-length input and output for 
GW-BASIC COM files. However, because of the low performance asso- 
ciated with telephone line communications, we recommend that you do 
not use GET and PUT for telephone communication. 


NOTE 


LSET, RSET, PRINT#, PRINT# 
USING, and WRITE# may be used 
to put characters in the random file 
buffer before executing a PUT state- 
ment. 


In the case of WRITE#, Microsoft 
GW-BASIC pads the buffer with spac- 
es up to the carriage return. Any 
attempt to read or write past the end 
of the buffer causes a “Field over- 
flow” error. 


For details on file I/O, see Chapter 5, “Working with Files and Devices.” 
Example: 


100 PUT 1, A$, B$, C$ 
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7.124 PUT STATEMENT — GRAPHICS 
Syntax: 

PUT (xl,yl),<array name>[,action verb] 
used with 

GET 9xl,y1)-(x2,y2),<array name> 


(xl,yl)inthe PUT statement specifies the point where a stored image is to 
be displayed onthe screen. The specified point is the coordinate of the top 
left corner of the image. If the image to be transferred is too large to fit in 
the current viewport, an “Illegal function call” error will result. 


<action verb> is one of: PSET, PRESET, AND, OR, XOR. 


PSET transfers the data point by point onto the screen. Each point has the 
exact color attribute it had when it was taken from the screen witha GET. 


PRESET is the same as PSET except that a negative image (black on 
white) is produced. 


AND is used when the image is to be transferred over an existing image on 
the screen. The resulting image is the product of the logical AND expres- 
sion; points that had the same color in both the existing image and the 
PUT image will remain the same color, points that do not have the same 
color in both the existing image and the PUT image will not. 


OR is used to superimpose the image onto an existing image. 


XOR is a special mode often used for animation. It causes the points on the 
screen to be inverted where a point exists in the array image. This behavior 
is exactly like that of the cursor. When an image is PUT against a complex 
background twice, the background is restored unchanged. This allows a 
user to move an object around the screen without erasing the background. 


The default <action verb> is XOR. 
Purpose: 


The GET and PUT statements are used together to transfer graphic images 
to and from the screen. 
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The GET statement transfers the screen image bounded by the rectangle 
described by the specified points into the array. 


The PUT statement transfers the image stored in the array onto the screen. 


The <action verb> specifies the interaction between the stored image and 
the one already on the screen. 


Remarks: 


One of the most useful things that can be done with GET and PUT is 
animation. Animation is performed as follows: 


1. PUT the object(s) on the screen. 
2. Recalculate the new position of the object(s). 


3. PUT the object(s) on the screen a second time at the old loca- 
tion(s) (using XOR) to remove the old image(s). 


4. Goto step 1, but this time PUT the object(s) at the new location. 


Movement done this way will leave the background unchanged. Flicker 
can be cut down by minimizing the time between steps 4 and | and by 
making sure that there is enough time delay between | and 3. If more than 
one object is being animated, every object should be processed at once, one 
step at a time. 


If it is not important to preserve the background, animation can be 
performed using the PSET action verb. The idea is to leave a border 
around the image when it is first gotten that is as large or larger than the 
maximum distance the object will move. Thus, when an object is moved, 
this border will effectively erase any points left by the previous PUT. This 
method may be somewhat faster than the method using XOR described 
above, since only one PUT is required to move an object (although you 
must PUT a larger image). 


It is possible to examine the x and y dimensions and even the data itself if 
an integer array is used. With the interpreter, the x dimension is in element 
0 of the array, and the y dimension is found in element |. (However, this 
will not always be true for the compiler.) Remember that integers are 
stored low byte first, then high byte, but the data is transferred high byte 
first (leftmost) and then low byte. 
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7.125 RANDOMIZE STATEMENT 
Syntax: 

RANDOMIZE [ <expression>] 
Purpose: 
To reseed the random number generator. 
Remarks: 


If <expression> is omitted, Microsoft GW-BASIC suspends program 
execution and asks for a value by printing 


Random Number Seed (-32768 to 32767)? 
before executing RANDOMIZE. 


If expression is a variable, the value of that variable is used to seed the 
random numbers. 


If <expression> is the word “TIMER” then the TIMER function is used 
to pass a random number seed. 


If the random number generator is not reseeded, the RND function 
returns the same sequence of random numbers each time the program is 
run. To change the sequence of random numbers every time the program Is 
run, placea RANDOMIZE statement at the beginning of the program and 
change the argument with each run. 
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Example: 


10 RANDOMIZE 
20 FOR I=1 TO 5 
30 PRINT RND; 

40 NEXT | 


will yield 


Random Number Seed (-32768 to 32767)? 3 
(user types 3) 


will yield 
885982 .4845668 .586328 .1194246 .7039225 


Random Number Seed (-32768 to 32767)? 4 
(user types 4 for new sequence) 


will yield 
803506 .1625462 .929364 .2924443  .322921 


Random Number Seed (-32768 to 32767)? 3 
(same sequence as first run) 


will yield 
885982 .4845668 .586328 .1194246 .7039225 


Note that the numbers your program produces may not be the same as the 


ones shown here. 
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7.126 READ STATEMENT 
Syntax: 

READ <list of variables> 
Purpose: 


To read values from a DATA statement and assign them to variables. (See 
“DATA Statement,” Section 7.27.) 


Remarks: 


A READ statement must always be used in conjunction with a DATA 
statement. READ statements assign variables to DATA statement values 
on a One-to-one basis. READ statement variables may be numeric or 
string, and the values read must agree with the variable types specified. If 
they do not agree, a “Syntax error” will result. 


A single READ statement may access one or more DATA statements 
(they will be accessed in order), or several READ statements may access 
the same DATA statement. If the number of variables in <list of varia- 
bles> exceeds the number of elements inthe DATA statement(s), an “Out 
of data” error message is printed. If the number of variables specified 1s 
fewer than the number of elements inthe DATA statement(s), subsequent 
READ statements will begin reading data at the first unread element. If 
there are no subsequent READ statements, the extra data is ignored. 


To reread DATA statements from the start, usethe RESTORE statement 
(see RESTORE Statement, Section 7.130). 


Example 1: 


80 FOR I=1 TO 10 

90 READ A(I) 

100 NEXT I 

110 DATA 3.08,5.19,3.12,3.98,4.24 
120 DATA 5.08,5.55,4.00,3.16,3.37 
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This program segment READs the values from the DATA statements into 
the array A. After execution, the value of A(1) will be 3.08, and so on. 


Example 2: 


10 PRINT “CITY”, “STATE”, “ ZIP” 

20 READ C$,S$,Z$ 

30 DATA “DENVER,”, “COLORADO” ,“80211” 
40 PRINT C$,S$,Z$ 


will yield 
CITY STATE ZIP 
DENVER, COLORADO 80211 


This program reads string and numeric data from the DATA statement in 
line 30. 


7-190 


Basic Commands, Functions and Statements 


7.127 REM STATEMENT 
Syntax: 
REM <remark> 
Purpose: 
To allow explanatory remarks to be inserted in a program. 
Remarks: 


REM statements are not executed but are output exactly as entered when 
the program is listed. 


REM statements may be branched into from a GOTO or GOSUB state- 
ment. Execution will continue with the first executable statement after the 
REM statement. 


Remarks may be added to the end of a line by preceding the remark witha 
single quotation mark instead of :REM. 


WARNING 


Do not use the single quotation form 
of the REM statement in a data 
statement, because it would be consid- 
ered legal data. 
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Example: 


120 REM CALCULATE AVERAGE VELOCITY 
130 FOR I=1 TO 20 
140 SUM=SUM + V(1) 


or 


120 FOR I=! TO 20 ’CALCULATE AVERAGE VELOCITY 
130 SUM=SUM+V(I) 
140 NEXT | 
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7.128 RENUM COMMAND 
Syntax: 
RENUM [[<new number>],[<old number>][,<increment>]]] 
Purpose: 
To renumber program lines. 
Remarks: 


<new number> is the first line number to be used in the new sequence. 
The default is 10. <old number> is the line in the current program where 
renumbering is to begin. The default is the first line of the program. 
<increment> is the increment to be used in the new sequence. The default 
is 10. 


RENUM also changes all line number references following GOTO, 
GOSUB, THEN, ELSE, ON...GOTO, ON...GOSUB, RESTORE, 
RESUME, and ERL statements to reflect the new line numbers. If a 
nonexistent line number appears after one of these statements, the error 
message “Undefined line number in xxxxx” is printed. The incorrect line 
number reference is not changed by RENUM, but line number yyyyy may 
be changed. 


NOTE 


RENUM cannot be used to change 
the order of program lines (for exam- 
ple, RENUM 15,30 when the pro- 
gram has three lines numbered 10, 20 
and 30) or to create line numbers 
greater than 65529. An “Illegal func- 
tion call” error will result. 
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Examples: 


RENUM Renumbers the entire program. The first 
new line number will be 10. Lines will be 
numbered in increments of 10. 


RENUM 300,,50 Renumbers the entire program. The first 
new line number will be 300. Lines will be 
numbered in increments of 50. 

RENUM 1000,900,20 Renumbers the lines from 900 up so they 
start with line number 1000 and are num- 
bered in increments of 20. 
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7.129 RESET COMMAND 
Syntax: 
RESET 
Purpose: 
To close all files. 
Remarks: 


RESET closes all open files and forces all blocks in memory to be written 
to disk. Thus, if the machine loses power, all files will be properly updated. 


All files must be closed before a disk is removed from its drive. 
Example: 


998 RESET 999 END 
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7.130 RESTORE STATEMENT 
Syntax: 

RESTORE [ <line number>] J 
Purpose: 
To allow DATA statements to be reread from a specified line. 
Remarks: 
Aftera RESTORE statement without a specified line number is executed, 
the next READ statement accesses the first item in the first DATA 


statement in the program. 


Is <line number> is specified, the next READ statement accesses the first 
item in the specified DATA statement. 


Example: 
10 READ A,B,C — 
20 RESTORE 


30 READ D,E,F 
40 DATA 57, 68, 79 
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7.131 RESUME STATEMENT 
Syntaxes: 


RESUME 

RESUME 0 

RESUME NEXT 
RESUME <line number> 


Purpose: 


To continue program execution after an error recovery procedure has 
been performed. 


Remarks: 


Any one of the four syntaxes shown above may be used, depending upon 
where execution Is to resume: 


RESUME Execution resumes at the statement 
or that caused the error. 

RESUME 0 

RESUME NEXT Execution resumes at the statement 


immediately following the one that 
caused the error. 


RESUME <line number> Execution resumes at <line num- 
ber>. 


A RESUME statement that is not in an error handling routine causes a 
“RESUME without error” message to be printed. 


Example: 


10 ON ERROR GOTO 900 


900 IF (ERR=230)AND(ERL=90) THEN PRINT 
“TRY AGAIN”: RESUME 80 
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7.132 RETURN STATEMENT 


See GOSUB...RETURN Statements, Section 7.54. 
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7.133 RIGHTS FUNCTION 
Syntax: 
RIGHT$(X$,1) 
Purpose: 
To return the rightmost I characters of string X$. 
Remarks: 


If 1is equal to the number of characters in X$ (LEN(X$)), returns X$. If I= 
0, the null string (length zero) is returned. 


Example: 


10 A$=“DISK BASIC” 

20 PRINT RIGHTS(A$,5) 
will yield 

BASIC 


Also see the LEFT$ and MID$ functions, Sections 7.70 and 7.88, 
respectively. 
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7.134 RMDIR STATEMENT 
Syntax: 

RMDIR<pathname> 
Purpose: 
To remove an existing directory 
Remarks: 
PATHNAME is the name of the directory which is to be deleted. RMDIR 
works exactly like the MS-DOS command RMDIR. The PATHNAME 
must be a string of less than 128 characters. 
The PATHNAME to be removed must be empty of any files except the 
working directory(’.’) and the parent directory(’..’) or else a “Path not 
found” or a “Path/ File Access error” is given. 
Example: 


RMDIR “\SALES” 


In this statement, the SALES directory on the current drive is to be 
removed. 
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7.135 RND FUNCTION 
Syntax: 
RND[(X)] 
Purpose: 
To return a random number between 0 and |. 
Remarks: 


The same sequence of random numbers is generated each time the pro- 
gram is run unless the random number generator is reseeded (see “RAN- 
DOMIZE Statement,” Section 7.125). However, X 0 always restarts the 
Same sequence for any given X. 


X > 0 or X omitted generates the next random number in the sequence. X 
= () repeats the last number generated. 


Example: 


10 FOR I=1 TO 5 
20 PRINT INT(RND*100); 
30 NEXT | 


might yield 
24 30 31 SI 5 


NOTE 


The values produced by the RND 
function may vary with different 
implementations of Microsoft 
GW-BASIC. 
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7.136 RUN STATEMENT/COMMAND 
Syntaxes: 


RUN [ <line number>] 
RUN <filespec>[,R] 


Purpose: 


To execute the program currently in memory, or to load a file into memory 
and run it. 


Remarks: 


For a program currently in memory, if <line number> is specified, 
execution begins on that line. Otherwise, execution begins at the lowest 
line number. Microsoft GW-BASIC always returns to command level 
after a RUN statement is executed. 


For running a program not in memory, the <filespec> is an optional 
device specification followed by a filename or pathname that conforms to 
MS-DOS 2.0’s rules for filenames. BASIC appends the default filename 
extension .BAS if the user specifies no extensions, and the file has been 
saved to the disk. 


RUN closes all open files and deletes the current contents of memory 
before loading the designated program. However, with the “R” option, all 
data files remain open. 


Example: 


RUN “NEWFIL”,R 
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7.137 SAVE COMMAND 
Syntax: 

SAVE <filespec>[{,A],P}] 
Purpose: 
To save a program file. 
Remarks: 
For saving a program in memory, the <filespec> is an optional device 
specification followed by a file name or pathname that conforms to 
MS-DOS 2.0’s rules for filenames. BASIC appends the default filename 
extension “.BAS” if the user specifies no extensions, and the file has been 
saved to the disk. 
The A option saves the file in ASCII format. If the A option is not 
specified, Microsoft GW-BASIC saves the file in a compressed binary 
format. ASCII format takes more space on the disk, but some actions 
require that files be in ASCII format. For instance, the MERGE com- 
mand requires an ASCII format file, and some operating system com- 
mands such as TYPE may require an ASCII format file. 
The P option protects the file by saving it in an encoded binary format. 
When a protected file is later RUN (or LOADed), any attempt to list or 
edit it will fail. 
Examples: 

SAVE “COM2”,A 
Saves the program COM2 in ASCII format. 

SAVE “PROG”,P 


Saves the program PROG.BAS as a protected file which cannot be 
altered. 
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7.138 SCREEN STATEMENT 
Syntax: 
SCREEN [mode] [,{burst] [,[apage] [,vpage]]] 


mode is a numeric expression resulting in an integer value of 0,1,2 or 3. 
Valid modes are: 


0 Text mode at current width (40 or 80). 
1 graphics mode (320x200). 
2 graphics mode (640x200) 
3. graphics mode (610x400) 


burst is a numeric expression resulting in a true or false value. It enables 
color. In text mode (mode=0), a false (zero) value disables color (black and 
white images only) and a true (non-zero) value enables color (allows color 
images). In graphics mode a true (non-zero) value will disable color, and a 
false (zero) value will enable color. 


apage (active page) is an integer expression in the range 0 to 7 in text mode 
or 0 to | in graphics mode. It selects the page to be written to by output 
statements to the screen. 

vpage (visual page) selects which page is to be displayed on the screen, in 
the same way as apage above. The visual page may be different than the 
active page. If omitted, vpage defaults to previous vpage. 


Purpose: 


To set the specifications for the display screen. The specifications may vary 
according to individual machines. 


Remarks: 
If all parameters are valid, the new screen mode is stored, the screen is 
erased, the foreground color is set to white, and the background and 


border colors are set to black. 


If the new screen mode is the same as the previous mode, nothing is 
changed. 
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If the mode is text, and only apage and vpage are specified, the effect is that 
of changing display pages for viewing. Initially, both active and visual 
pages default to 0 (zero). By manipulating active and visual pages, you can 
display one page while building another. Then you can switch visual pages 
instantaneously. 


NOTE 


There is only one cursor shared be- 
tween all the pages. If you are going to 
switch active pages back and forth, 
you should save the cursor position 
on the current active page (using 
POS(0) and CSRLIN), before chang- 
ing to another active page. Then when 
you return to the original page, you 
can restore the cursor position using 
the LOCATE statement. 


Any parameter may be omitted. Omitted parameters, except vpage, 
assume the old value. 


Any values entered outside of the ranges indicated will result in an “Illegal 
function call” error. Previous values are retained. 


Example: 
10 SCREEN 0,1,0,0 
Selects text mode with color, and sets active and visual page to 0. 
20 SCREEN ,,1,2 
Mode and color burst remain unchanged. Active page is set to | and 


display page to 2. 


~ 
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7.139 SCREEN FUNCTION 
Syntax: 
SCREEN(row,col[,z]) 
row 1S a numeric expression in the range | to 25. 


col is a numeric expression in the range | to 40 or | to 80 depending upon 
the WIDTH setting. 


z is anumeric expression which evaluates to a true or false value. z is only 
valid in text mode. 


Purpose: 
To read a character or its color from a specified screen location. 
Remarks: 
The ordinate of the character at the specified coordinates is stored in the 
numeric variable. If the optional parameter z is given and is non-zero, the 
color attribute for the character is returned instead. 
Example: 

100 x = SCREEN (10,10) 


If the character at (10,10) is A, then the function would return 65, the 
ASCII code for A. 


100 x = SCREEN (1,1,1) 


Returns the color attribute of the character in the upper left corner of the 
screen. 
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7.140 SGN FUNCTION 
Syntax: 
SGN(X) 
Purpose: 
To indicate the value of X, relative to zero: 
If X>0, SGN(X) returns 1. 
If X=0, SGN(X) returns 0. 
If X<0, SGN(X) returns -1. 
Example: 


ON SGN(X)+2 GOTO 100,200,300 


Branches to 100 if X is negative, 200 if X is 0, and 300 if X is positive. 
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7.141 SHELL STATEMENT 
Syntax: 

SHELL [<command-string>] 
Purpose: 


To exit the BASIC program, run a COM or EXE or BAT program, ora 
built-in DOS function such as DIR or TYPE, and return to the BASIC 
program at the line after the SHELL statement. 


Remarks: 


A COM, EXE, or BAT program or DOS function which runs under the 
SHELL statement is called a “Child process.” Child processes are exe- 
cuted by SHELL loading and running a copy of COMMAND with the 
“/C” switch. By using COMMAND inthis way, command line parameters 
are passed to the child. Standard input and output may be redirected, and 
built-in commands such as DIR, PATH, and SORT may be executed. 


The <command-string> must bea valid string expression containing the 
name of a program to run and (optionally) command arguments. 


The program name in <command-string> may have any extension you 
wish. If no extension is supplied, COMMAND will look for a .COM file, 
then a .EXE file, and finally, a .BAT file. If COMMAND is not found, 
SHELL will issue a “File not found” error. No error is generated if 
COMMAND cannot find the file specified in <command-string>. 


Any text separated from the program name by at least one blank will be 
processed by COMMAND as program parameters. 


BASIC remains in memory while the child process is running. When the 
child finishes, BASIC continues. 


Some versions of GW-BASIC will not allow the user to SHELL to another 
copy of BASIC. BASIC, when run as a Child process, will recognize this 
before initialization and return to the Parent copy of BASIC after issuing 
the message: “You cannot Shell to BASIC”. This restriction is provided as 
an implementation option for cases where it is necessary to protect the 
integrity of the BASIC Parent. 
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SHELL with no <command-string> will give you a new COMMAND 
shell. You may now do anything that COMMAND allows. When ready to 
return to BASIC, enter the DOS command: EXIT. 


Examples: 


SHELL ’get a new COMMAND 


ADIR {user types DIR to see files} 
AEXIT luser types EXIT to return to BASIC} 
Ok now back in BASIC 


Write some data to be sorted, SHELL sort to sort it, then read the sorted 
data to write a report. 


900 OPEN “SORTIN.DAT” FOR OUTPUT AS 1 

950 REM ** write data to be sorted 

1000 CLOSE 1 

1010 SHELL “SORT SORTIN.DAT SORTOUT.DAT” 
1020 OPEN “SORTOUT.DAT” FOR INPUT AS |! 
1030 REM ** Process the sorted data 


10 SHELL “DIR | SORT FILES. 
20 OPEN “FILES.” FOR INPUT AS | 


Also see BASIC and Child Processes, Section 5.7. 
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7.142 SIN FUNCTION 
Syntax: 

SIN(X) 
Purpose: 
To return the sine of X, where X is in radians. 
Remarks: 

COS(X) = SIN(X+3.14159/ 2). 
Example: 


PRINT SIN(1.5) 
will yield 
9974951 


See also COS Function, Section 7.23. 
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7.143 SOUND STATEMENT 
Syntax: 
SOUND <freq>,<duration> 


<freq> is the desired frequency in hertz. This must be a numeric expres- 
sion returning an unsigned integer. 


<duration> is the duration in clock ticks. Clock ticks occur 18.2 times per 
second. This must be a numeric expression returning an unsigned integer 
in the range 0 to 65535. 


Purpose: 


To generate a sound through the speaker. Requires optional sound and 
joystick board. 


Remarks: 

If the duration is zero, any current SOUND statement that is running will 
be turned off. If no SOUND statement is currently running, a SOUND 
statement with a duration of zero will have no effect. 

Example: 


30 SOUND RND*1000+37,2 


This statement creates random sounds. 
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7.144 SPACES FUNCTION 
Syntax: 
SPACE$(I) 
Purpose: 
To return a string of spaces of length I. 
Remarks: 


The expression I is rounded to an integer and must be in the range 0 to 255. 


Example: 


10 FOR I=1 TO 5 
20 X$=SPACES$(I) 
30 PRINT X$;] 
40 NEXT | 
will yield 
l 
2 
3 
4 
5 


Also see SPC Function, Section 7.145. 
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7.145 SPC FUNCTION 
Syntax: 

SPC(n) 
Purpose: 


To skip spaces in a PRINT statement. n is the number of spaces to be 
skipped. 


Remarks: 


SPC may only be used with PRINT and LPRINT statements. n must bein 
the range 0 to 255. A’;’ is assumed to follow the SPC(n) command. 


Example: 


PRINT “OVER” SPC(15) “THERE” 
will yield 
OVER THERE 


Also see SPACE$ Function, Section 7.144. 
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7.146 SQR FUNCTION 
Syntax: 
SQR(X) 
Purpose: 
To return the square root of X. 
Remarks: 
X must be > = 0. 
Example: 


10 FOR X=10 TO 25 STEP 5 
20 PRINT X, SQR(X) 


30 NEXT X 

will yield 

10 3.162278 
15 3.872984 
20 4.472136 
25 5 
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7.147 STICK FUNCTION 
Syntax: 
STICK(n) 
(n) is a numeric expression returning an unsigned integer in the range 0 to 3. 
Purpose: 


To return the x and y coordinates of the two joysticks. Requires optional 
sound and joystick board. 


Remarks: 
The values returned for n can be: 


0 Returns the x coordinate for joystick A. Also stores the x and y 
values for both joysticks for the following function calls: 


1 Returns the y coordinate of joystick A. 
2 Returns the x coordinate of joystick B. 
3 Returns the y coordinate of joystick B. 


Example: 


10 CLS 

20 LOCATE 1,1 

30 PRINT “X=5”;STICK(0) 
40 PRINT “Y=5”;STICK(1) 
50 GOTO 20 


This example creates an endless loop to display the value of the x,y 
coordinate for joystick A. 
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7.148 STOP STATEMENT 
Syntax: 
STOP 
Purpose: 
To terminate program execution and return to command level. 
Remarks: 


STOP statements may be used anywhere in a program to terminate 
execution. STOP is often used for debugging. When a STOP is encoun- 
tered, the following message is printed: 


Break in line nnnnn 
The STOP Statement doesn’t close files. 


Microsoft GW-BASIC always returns to command level after a STOP is 
executed. Execution is resumed by issuing a CONT command (see Section 
7.22). 


Example: 


10 INPUT A,B,C 

20 K=A “* 2*5.3:L=B * 3/.26 
30 STOP 

40 M=C*K+100:PRINT M 


will yield 
112.3 
BREAK IN 30 
PRINT L 
30.76923 


CONT 
115.9 
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7.149 STR$ FUNCTION 
Syntax: 
STR$(n) 
Purpose: 
To return a string representation of the value of n. 
Example: 
5 REM ARITHMETIC FOR KIDS 


10 INPUT “TYPE A NUMBER”;N 
20 ON LEN(STRS$(N)) GOS UB 30,100,200,300,400,500 


Also see VAL Function, Section 7.163. 
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7.150 STRIG FUNCTION 
Syntax: 
STRIG(n) 
where x is a numeric variable for storing the result of the function. 


(n) is a numeric expression returning an unsigned integer in the range 0 to 
7, designating which trigger is to be checked. 


Purpose: 


To return the status of a specified joystick trigger. Requires optional 
sound and joystick board. 


Remarks: 
In the STRIG(n) function, the values returned for (n) can be: 


0 Returns -1 if trigger Al was pressed since the last STRIG(0) 
function call, returns 0 if not. 


1 Returns -1 if trigger Al is currently down, 0 if not. 


2 Returns -! if trigger BI was pressed since the last STRIG(2) 
function call, 0 if not. 


3 + Returns -1 if trigger BI is currently down, 0 if not. 


Returns —1 if trigger A2 was pressed since the last STRIG(4) 
function call, returns 0 if not. 


5 Returns -1 if trigger A2 is currently pressed, returns 0 if not. 


Returns -1 if trigger B2 was pressed since the last STRIG(6) 
function call, returns 0 if not. 


7 Returns —1 if trigger B2 is currently pressed, returns 0 if not. 
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When a joystick event trap occurs, that occurrence of the event is de- 
stroyed. Therefore, the x=STRIG(n) function will always return false 
inside a subroutine, unless the event has been repeated since the trap. Soif 
you wish to perform different procedures for various joysticks, you must 
set up a different subroutine for each joystick, rather than including all the 
procedures in a single subroutine. 


Example: 


10 IF STRIG(O) THEN BEEP 
20 GOTO 10 


In this example an endless loop is created to beep whenever the trigger 
button on joystick 0 is pressed. | 
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7.151 STRIG ON, STRIG OFF, STRIG STOP STATEMENTS 
Syntax: 

STRIG(n) ON 

STRIG(n) OFF 

STRIG(n) STOP 


n may be 0, 2, 4, or 6, and indicates the trigger to be trapped as follows: 


0 trigger Al 


2 trigger Bl 

4 trigger A2 

6 trigger B2 
Purpose: 


The STRIG(n) ON statement enables event trapping of joystick activity. 
Requires optional sound and joystick board. 


The STRIG(n) OFF statement disables event trapping of joystick activity. 


The STRIG(n) STOP statement disables event trapping of joystick activ- 
ity. 


Remarks: 


The STRIG(n) ON statement enables joystick event trapping by an ON 
STRIG statement (see STRIG ON Statement, Section 7.151). While trap- 
ping is enabled, and if a non-zero line number is specified in the ON 
STRIG statement, GW-BASIC checks between every statement to see if 
the joystick trigger has been pressed. 


The STRIG OFF statement disables event trapping. If asubsequent event 
occurs (1.e., if the trigger is pressed), it will not be remembered when the 
next STRIG ON 1s invoked. 


The STRIG STOP statement disables event trapping, but if an event 


occurs it will be remembered, and the event trap will take place as soon as 
trapping is reenabled. 
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7.152 STRING$ FUNCTION 
Syntaxes: 


STRINGS$(I,J) 
STRINGS$(I,X$) 


Purpose: 


To return a string of length I whose characters all have ASCII code J or the 
first character of X$. 


Examples: 
10 DASH$ = STRING$(10,45) 
20 PRINT DASH$;“MONTHLY REPORT”;DASH$ 
will yield 


10 LET A$ = “HOUSTON” 
20 LET X$ = STRING$(8,A$) 
30 PRINT X$ 


will yield 
HHHHHHHH 
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7.153 SWAP STATEMENT 
Syntax: 

SWAP <variable>,<variable> 
Purpose: 
To exchange the values of two variables. 
Remarks: 


Any type variable may be swapped (integer, single precision, double 
precision, string), but the two variables must be of the same type or a 
“Type mismatch” error results. 


If the second variable is not already defined when SWAP is executed, an 
“Tegal function call” error will result. 


Example: 


10 AS=“ ONE ”: BS=“ ALL ” 
: C$=“FOR” 

20 PRINT AS C$ BS 

30 SWAP AS,B$ 

40 PRINT AS C$ BS 


will yield 


ONE FOR ALL 
ALL FOR ONE 
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7.154 SYSTEM COMMAND 
Syntax: 
SYSTEM 
Purpose: 
To close all open files and return control to the operating system. 
Remarks: 


When a SYSTEM command 1s executed, all files are closed, and BASIC 
performs an exit to the operating system. 
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7.155 TAB FUNCTION 
Syntax: 
TAB(I) 
Purpose: 
To move the print position to I. 
Remarks: 
If the current print position is already beyond space I, TAB goes to that 
position on the next line. Space | is the leftmost position, and the right- 
most position is the width minus one. I must be in the range | to 255. TAB 
may only be used in PRINT and LPRINT statements. 
Example: 
10 PRINT “NAME” TAB(25) “AMOUNT”: PRINT 
20 READ A$,B$ 


30 PRINT A$ TAB(25) BS 
40 DATA “G. T. JONES”,“$25.00” 


will yield 
NAME AMOUNT 
G. T. JONES $25.00 
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7.156 TAN FUNCTION 
Syntax: 
TAN(X) 
Purpose: 
To return the tangent of X. X should be given in radians. 
Remarks: 
With the interpreter, if TAN overflows, the “Overflow” error message is 
displayed, machine infinity with the appropriate sign is supplied as the 
result, and execution continues. 


Example: 


10 Y=Q*TAN(X)/2 
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7.157 TIMES STATEMENT 
Syntax: 
TIME$=<string expression> 
<string expression> returns a string in one of the following forms: 


hh (sets the hour; minutes and seconds default to 00) 
hh:mm (sets the hour and minutes; seconds default to 00) 
hh:mm:ss (sets the hour, minutes, and seconds) 


Purpose: 


To set the time. This statement complements the TIMES function, which 
retrieves the time. 


Remarks: 
A 24-hour clock is used; 8:00 p.m., therefore, would be entered as 20:00:00. 
Example: 

10 TIME$=“08:00:00” 


The current time is set at 8:00 a.m. 
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7.158 TIMES FUNCTION 
Syntax: 

TIME$ 
Purpose: 


To retrieve the current time. (To set the time, use the TIME$ statement, 
described in Section 7.157.) 


Remarks: 

The TIME$ function returns an eight-character string in the form 
hh:mm:ss, where hh is the hour (00 through 23), mm is minutes (00 
through 59), and ss is seconds (00 through 59). A 24-hour clock is used; 
8:00 p.m., therefore, would be shown as 20:00:00. 

Example: 


10 PRINT TIME$ 


Prints the time, calculated from the time set with the TIMES statement. 
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7.159 TIMER FUNCTION 
Syntax: 

TIMER J 
Purpose: 


Return a single-precision number representing the number of seconds that 
have elapsed since midnight. 
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7.160 TIMER ON, TIMER OFF, TIMER STOP STATEMENTS 
Syntax: 


TIMER ON 
TIMER OFF 
TIMER STOP 


Purpose: 


TIMER ON enables event trapping during real time. TIMER OFF dis- 
ables event trapping during real time. TIMER STOP suspends real time 
event trapping. 


Remarks: 


The TIMER ON statement enables real time event trapping by an ON 
TIMER statement (see “ON TIMER Statement,” Section 7.101). While 
trapping is enabled with the ON TIMER statement, GW-BASIC checks 
between every statement to see if the timer has reached the specified level. 
If it has, the ON TIMER statement is executed. 


TIMER OFF disables the event trap. If an event takes place, it is not 
remembered if a subsequent TIMER ON is used. 


TIMER STOP disables the event trap, but if an event occurs, it is remem- 
bered and an ON TIMER statement will be executed as soon as trapping 1s 


enabled. 


Also see ON TIMER Statement, Section 7.101. 
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7.161 TRON/TROFF STATEMENTS/COMMANDS 
Syntax: 


TRON 
TROFF 


Purpose: 
To trace the execution of program statements. 
Remarks: 


As an aid in debugging, the TRON statement may be executed in either 
direct or indirect mode. With TRON in operation, each line number of the 
program is printed on the screen as it 1s executed. 


The numbers appear enclosed in square brackets. The trace flag is disabled 
with the TROFF statement (or when a NEW command Is executed). 


Example: 


TRON 


10 K=10 

20 FOR J=1 TO 2 
30 L=K+10 

40 PRINT J;K;L 
50 K=K+10 

60 NEXT J 

70 END 


will yield 


[10][20][30][40] 1 10 20 
[50][60][30]1[40] 2 20 30 
[50}[60][ 70] 
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7.162 USR FUNCTION 
Syntax: 
USR[<digit>][(<argument>)] 


where <digit> specifies which USR routine is being called. See the DEF 
USR statement, Section 7.33, for rules governing <digit>. If <digit> is 
omitted, USRO is assumed. 


<argument> is the value passed to the subroutine. It may be any numeric 
or string expression. 


Purpose: 
To call an assembly language subroutine. 
Remarks: 


If a segment other than the default segment (data segment) is to be used, a 
DEF SEG statement must be executed prior to a USR function call. The 
address given in the DEF SEG statement determines the segment address 
of the subroutine. 


For each USR function, a corresponding DEF USR statement must be 
executed to define the USR call offset. This offset and the currently active 
DEF SEG segment address determine the starting address of the 
subroutine. 


Example: 


100 DEF SEG=&H8000 
110 DEF USRO=0 

120 X=5 

130 Y = USRO(X) 

140 PRINT Y 


The type (numeric or string) of the variable receiving the value must be 
consistent with the argument passed. This setup of the string space differs 
from that of the interpreter. 
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7.163 VAL FUNCTION 
Syntax: 

VAL(<string>) - 
<string> must be a numeric character stored as a string. 
Purpose: 
To return the numeric value of string <string>. The VAL function also 


strips leading blanks, tabs, and linefeeds from the argument string. For 
example, 


VAL(“ -3”) 
returns —3. 
Example: 


10 READ NAME$,CITY$,STATE$,ZIP$ 

20 IF VAL(ZIP$)<90000 OR VAL(ZIP$)>96699 
THEN PRINT NAME$ TAB(25) “OUT OF STATE” 

30 IF VAL(ZIP$)>=90801 AND VAL(ZIP$)<=90815 
THEN PRINT NAME$ TAB(25) “LONG BEACH” 


See the STR$ function, Section 7.149, for details on numeric-to-string 
conversion. 
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7.164 VARPTR FUNCTION 
Syntax I: 

VARPTR(<variable name>) 
Syntax 2: 

VARPTR(#<file number>) 
Purpose: 
Syntax | 


Returns the address of the first byte of data identified with <variable 
name>. The variable must have been defined prior to the execution of the 
VARPTR function. Otherwise an “Illegal function call” error results. 
Variables are defined by executing any reference to the variable. 


Any type variable name may be used (numeric, string, array). For string 
variables, the address of the first byte of the string descriptor is returned 
(see “Assembly Language Subroutines,” Section 6.1 for discussion of the 
string descriptor). The address returned will be an integer in the range 
32767 to -32768. If a negative address is returned, add it to 65536 to obtain 
the actual address. 
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VARPTR is usually used to obtain the address of a variable or array so 
that it may be passed to an assembly language subroutine. A function call 
of the form VARPTR(A(0)) is usually specified when passing an array, so 
that the lowest-addressed element of the array is returned. 


NOTE 


All simple variables should be assigned 
before calling VARPTR for an array, 
because the addresses of the arrays 
change whenever a new simple varia- 
ble is assigned. 


Syntax 2 

For sequential files, returns the starting address of the disk I/O buffer 
assigned to <file number>. For random files, returns the address of the 
FIELD buffer assigned to <file number>. 


Example: 


100 X=USR(VARPTR(Y)) 
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7.165 VARPTR$ FUNCTION 
Syntax: 
VARPTRS(<variable name>) 
where <variable name> is the name of a variable in the program. 
Purpose: 


To return a character form of the memory address of the variable in a form 
that is compatible for programs that may later be compiled. 


Remarks: 


VARPTRS$ is primarily used to execute substrings with the DRAW and 
PLAY statements (Sections 7.36 and 7.111, respectively) in programs that 
will later be compiled. With programs that will not be later compiled, the 
standard syntax of the PLAY and DRAW statements will be sufficient to 
produce desired effects. 


The variable must have been defined prior to the execution of the 


VARPTR function. Otherwise an “Illegal function call” error results. 
Variables are defined by executing any reference to the variable. 
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VARPTRS$ returns a three-byte string in the form: 


byte 0 = type 
byte | = low byte of address 
byte 2 = high byte of address 


Note, however, that the individual parts of the string are not considered 
characters. 


NOTE 


Because array addresses, string ad- 
dresses and file data block change 
whenever a new variable is assigned, 
it is unsafe to save the result of a 
VARPTR function in a variable. It is 
recommended that VARPTR is exe- 
cuted before each use of the result. 


Example: 
10 PLAY “X”+VARPTRS$(A$) 


Uses the subcommand X (execute), plus the contents of A§, as the string 
expression in the PLAY statement. 
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7.166 VIEW STATEMENT 
Syntax: 


VIEW [ [SCREEN] [(Vx1,Vy1)-(Vx2,Vy2) L[<color>] 
[.[<border>]]]] ] 


Purpose: 
To define screen limits for graphics activity. 
Remarks: 


VIEW defines a “Physical Viewport” limit from Vx1,Vy1 (upper left x,y 
coordinates) to Vx2,Vy2 (lower right x,y coordinates). The x and y coor- 
dinates must be within the physical bounds of the screen. The physical 
viewport defines the rectangle within the screen into which graphics may 
be mapped. 


RUN, and RUN, SCREEN and VIEW with no arguments, define the 
entire screen as the viewport. 


The <color> atribute allows the user to draw a line surrounding the 
viewport if space for a border is available. If border is omitted, no border is 
drawn. 


The <border> attribute allows the user to draw a line surrounding the 
viewport if space for a border is available. If border is omitted, no border is 
drawn. 


The [SCREEN] option dictates that the x and y coordinates are absolute 


to the screen, not relative to the border of the physical viewport, and only 
graphics within the viewport will be plotted. 
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Examples: 
For the form: 

VIEW (Vx1,Vy1)-(Vx2, Vy2) 
all points plotted are relative to the viewport. That is, Vxl and Vy! are 
added to the x and y coordinates before putting the point down on the 
screen. 
If: 

VIEW (10,10)-(200, 100) 


were executed, then the point set down by the statement PSET (0,0) would 
actually be at the physical screen location 10,10. 


For the form: 
VIEW SCREEN (Vx1,Vy1)-(Vx2, Vy2) 
all coordinates are screen absolute rather than viewport relative. 
If: 
VIEW SCREEN (10,10)-(200,100) 
were executed, then the point set down by the statement PSET (0,0),3 
would actually not appear because 0,0 is outside of the viewport. PSET 


(10,10),3 is within the viewport, and places the point in the upper-left hand 
corner of the viewport. 
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A number of VIEW statements may be executed. If the newly described 
viewport is not wholly within the previous viewport, the screen can be 
re-initialized with the VIEW statement. Then the new viewport may be 
stated. If the new viewport is entirely within the previous one, as in the 
following example, the intermediate VIEW statement isn’t necessary. This 
example opens three viewports, each smaller than the previous one. In 
each case, a line that is defined to go beyond the borders is programmed, 
but appears only within the viewport border. 


260 CLS 

280 VIEW: REM ** Make the viewport the entire screen. 
300 VIEW (10,10) — (300,180),,1 

320 CLS 

340 LINE (0,0) - (310,190), 1 

360 LOCATE 1,11: PRINT “A big viewport” 
380 VIEW SCREEN (50,50)-(250,150),, 1 

400 CLS:REM** Note, CLS clears only viewport 
420 LINE (300,0)-(0,199), 1 

440 LOCATE 9,9: PRINT “A medium viewport” 
460 VIEW SCREEN (80,80)-(200,125),, | 

480 CLS 

500 CIRCLE (150,100),20,1 

520 LOCATE 11,9: PRINT “A small viewport” 
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7.167 VIEW PRINT STATEMENT 
Syntax: 
VIEW PRINT [<top screen line> TO <bottom screen line>] 
Purpose: 
To set the boundaries of the screen text window. 
Remarks: 


VIEW PRINT without top and bottom line parameters initializes the 
whole screen area as the text window. 


Statements and functions which operate within the defined text window 
include CLS, LOCATE PRINT and SCREEN. 


The Screen Editor will limit functions such as scroll and cursor movement 
to the text window. 


Also see the VIEW Statement, Section 7.166. 
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7.168 WAIT STATEMENT 
Syntax: 

WAIT <port number>,][,J] 
where I and J are integer expressions. 
Purpose: 


To suspend program execution while monitoring the status of a machine 
input port. 


Remarks: 


The WAIT statement causes execution to be suspended until a specified 
machine input port develops a specified bit pattern. The data read at the 
port is exclusive OR’ed with the integer expression J, and then AND’ed 
with I. If the result is zero, Microsoft GW-BASIC loops back and reads the 
data at the port again. If the result is nonzero, execution continues with the 
next statement. If J is omitted, it is assumed to be zero. 


WARNING 


It is possible to enter an infinite loop 
with the WAIT statement, in which 
case it will be necessary to manually 
restart the machine. To avoid this, 
WAIT must have the specified value 
at <port number> during some 
point in the program execution. 


Example: 


100 WAIT 32,2 
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7.169 WHILE...WEND STATEMENTS 
Syntax: 


WHILE <expression> 
[<loop statements>] 


WEND 
Purpose: 


To execute a series of statements in a loop as long as a given condition is 
true. 


Remarks: 


If <expression> is not zero (i.e., true), <loop statements> are executed 
until the WEND statement is encountered. Microsoft GW-BASIC then 
returns to the WHILE statement and checks <expression>. If it is still 
true, the process is repeated. If it is not true, execution resumes with the 
statement following the WEND statement. 


WHILE/WEND loops may be nested to any level. Each WEND will 
match the most recent WHILE. An unmatched WHILE statement causes 
a “WHILE without WEND” error, and an unmatched WEND statement 
causes a “WEND without WHILE” error. 
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Example: 


90 "BUBBLE SORT ARRAY A$ WHICH HAS J ELEMENTS. 
100 FLIPS=1 "FORCE ONE PASS THRU LOOP 
110 WHILE FLIPS 
115 FLIPS=0 
120 FOR IF! TO J-1 
130 IF A$(1)> AS$(I+1) THEN 
SWAP A$(I), A$(I+1): FLIPS=1 
140 NEXTI 
150 WEND 


NOTE 


Do not direct program flow into a 
WHILE/ WEND loop without enter- 
ing through the WHILE statement. 
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7.170 WIDTH STATEMENT 
Syntax 1: 

WIDTH [LPRINT ]<size> 
Syntax 2: 

WIDTH <cfile number>,<size> 
Syntax 3: 

WIDTH <device>,<size> 


<size> is anumeric expression in the range 0 to 255. It specifies the width 
of the printed line. The default width is 72 characters. 


If <integer expression> is 255, the line width is “infinite”; that 1s, 
Microsoft GW-BASIC never inserts a carriage return. However, the posi- 
tion of the cursor or the print head, as given by the POS or LPOS function, 
returns to zero after position 255. 


<file number> is a numeric expression in the range | to 15. This is the 
number of the file that is open. 


<device> is a string expression indicating the device that is to be used. 
Purpose: 


To set the printed line width in number of characters for the screen or line 
printer. 
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Remarks: 


Syntax I: If the LPRINT option is omitted, the line width is set at the 
screen. If LPRINT is included, the line width is set at the line printer. 


The WIDTH statement may cause the screen to be cleared. 


Syntax 2: With Syntax 2, if the file is open, the width is immediately 
changed to the specified size. This allows the width to be changed while the 
file is open. 


Syntax 3: With Syntax 3, the default line width for the specified device 1s 
set to <size>. The line widths of currently open files are not modified. A 
subsequent OPEN <filespec> FOR OUTPUT AS #n will use the 
specified value for the width initially. 


Example: 


10 WIDTH “LPT1:”, 5 

20 OPEN “LPTI:” FOR OUTPUT AS | 
30 PRINT 1, “1234567890” 

35 PRINT 1 

40 WIDTH 1, 6 

50 PRINT 1, “1234567890” 

RUN 


will yield 


12345 
67890 


123456 
7890 
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7.171 WINDOW STATEMENT 
Syntax: 
WINDOW [[SCREEN] (Wx1,Wy1)-(Wx2, Wy2)] 


where (Wx1,Wy1)-(Wx2,Wy2) are the world coordinates specified by the 
programmer to define the coordinates of the lower left and upper right 
screen border. 


SCREEN inverts the y axis of the world coordinates so that screen 
coordinates coincide with the traditional Cartesian arrangement: x 
increases left to right, and y decreases top to bottom. 


Purpose: 


To define the logical dimensions of the current viewport. 


Remarks: 
WINDOW allows the user to redefine the screen border coordinates. 


WINDOW allows the user to draw lines, graphs, or objects in space not 
bounded by the physical dimensions of the screen. This is done by using 
programmer-defined coordinates called “World coordinates”. When the 
programmer has redefined the screen, graphics can be drawn within a 
customized mapping system. 


BASIC converts world coordinates into physical coordinates for subse- 
quent display within the current viewport. To make this transformation 
from world space to the physical space of the viewing surface (screen), one 
must know what portion of the (floating point) world coordinate space 
contains the information to be displayed. This rectangular region in world 
coordinate space is called a Window. 


RUN, or WINDOW with no arguments, disables “Window” transforma- 
tion. 


The WINDOW SCREEN variant inverts the normal Cartesian direction 
of the y coordinate. Consider the following: 
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In the default, a section of the screen appears as: 


50,0 


\/ y increases 
100,0 


50,100 100,100 





Now execute: 
WINDOW (-1,-1)-(1,]) 


and the screen appears as: 


0,1 
y increases 


0,0 


7% 


\ 7 y decreases 
0,-1 





If the variant: 
WINDOW SCREEN (-1,-1)-(1,]) 
is executed then the screen appears as: 
0,-1 


/\y decreases 


0,0 


\/ y increases 
0,1 





The following example illustrates two lines with the same endpoint coor- 
dinates. The first is drawn on the default screen, and the second is on a 
redefined window. 


200 LINE (100,100) — (150,150), 1 

220 LOCATE 2,20:PRINT “The line on the default screen” 

240 WINDOW SCREEN (100,100) — (200,200) 

260 LINE (100,100) — (150,150), 1 

280 LOCATE 8,18:PRINT“& the same line on a redefined window” 
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7.172 WRITE STATEMENT 
Syntax: 

WRITE [<list of expressions>] 
Purpose: 
To output data to the screen. 
Remarks: 
If <list of expressions> is omitted, a blank line is output. If <list of 
expressions> is included, the values of the expressions are output to the 
screen. The expressions in the list may be numeric and/or string expres- 
sions. They must be separated by commas. 
When the printed items are output, each item is separated from the last by 
a comma. Printed strings are delimited by quotation marks. After the last 


item in the list is printed, GW-BASIC inserts a carriage return/ linefeed. 


WRITE outputs numeric values using the same format as the PRINT 
statement. (See Section 7.119.) 


Example: 


10 A=80:B=90:C$=“THAT’S ALL” 
20 WRITE A,B,C$ 

will yield 

80, 90,“°THAT’S ALL” 
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7.173 WRITE#<file number>,<list of expressions> 
Purpose: 
To write data to a sequential file. 
Remarks: 
<file number> is the number under which the file was OPENed in “O” 
mode (see “OPEN Statement,” Section 7.102). The expressions in the list 
are string or numeric expressions. They must be separated by commas. 
The difference between WRITE# and PRINT# is that WRITE# inserts 
commas between the items as they are written to the file and delimits 
strings with quotation marks. Therefore, it is not necessary for the user to 
put explicit delimiters in the list. A carriage return/linefeed sequence is 
inserted after the last item in the list 1s written to the file. 
Example: 

Let A$S=“CAMERA” and B$=“93604-1” 
The statement: 

WRITE#1,A$,B$ 
writes the following image to disk: 

“CAMERA”,“93604-1” 
A subsequent INPUT# statement, such as 


INPUT#1,Z$,B$ 


would input “CAMERA” to A§ and “93604-1” to BS. 
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ASCII Character 
Codes 





ASCII Control ASCII 
value Character character value Character 
000 (null) NUL 032 (space) 
001 © SOH 033 ! 
002 @ STX 034 " 
003 y ETX 035 # 
004 « EOT 036 S 
005 fe ENQ 037 % 
006 & ACK 038 & 
007 (beep) BEL 039 
008 | BS 040 ( 
009 O see note | HT 041 ) 
010 see note 1 LF 042 * 
O11 fo) see note 1 VT 043 ~ 
012 Q see note | FF | 044 

013 2 see note 1 CR 045 

014 J SO 046 
015 Xt SI 047 / 
016 » DLE 048 0 
017 4 DCI 049 ! 
018 DC2 050 2 
019 ' DC3 051 3 
020 1 DC4 052 4 
021 § NAK 053 5 
022 oa SYN 054 6 
023 + ETB 055 7 
024 { CAN 056 8 
025 | EM 057 9 


ASCII Character Codes 


026 
027 
028 
029 
030 
031 
x B 


~>ftr{ 


see note | 
see note | 
see note | 
seen note | 


SUB 058 
ESC O59 ; 
FS 060 < 
GS 061 = 
RS 062 es 
US 063 q 


Note 1: These ASCII values do not display a displayable character but are 
interpreted as control characters. One way to get the displayable character 
for one of these particular ASCII values in GW-BASIC, is to ‘POKE’ that 
value into the appropriate locaion in video RAM. 
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Error Messages 


NUMBER 


l 


MESSAGE 


NEXT without FOR 


A variable ina NEXT statement does not correspond to any 
previously executed, unmatched FOR statement variable. 


Syntax error 


A line is encountered that contains some incorrect sequence 
of characters (such as an unmatched parenthesis, misspelled 
command or statement, incorrect punctuation, etc.). 


With GW-BASIC, the incorrect line will be part of a DATA 
Statement. 


Microsoft GW-BASIC Interpreter automatically enters edit 
mode at the line that caused the error. 

Return without GOSUB 

A RETURN statement is encountered for which there is no 
previous, unmatched GOSUB statement. 

Out of data 


A READ statement is executed when there are no DATA 
statements with unread data remaining in the program. 
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NUMBER 


5 


10 


MESSAGE 


Illegal function call 


A parameter that is out of range 1s passed to a math or string 
function. An FO error may also occur as the result of: 


1. A negative or unreasonably large subscript. 

. A negative or zero argument with LOG. 

. A negative argument to SQR. 

. A negative mantissa with a noninteger exponent. 


WM" & W NN 


. A call to a USR function for which the starting 
address has not yet been given. 


6. Animproper argument to MID$, LEFT$, RIGHTS, 
INT, OUT, WAIT, PEEK, POKE, TAB, SPC, 
STRING$, SPACES, INSTR, or ON...GOTO. 


7. A negative record number used with GET or PUT. 


Overflow 


The result of a calculation is too large to be represented in 
Microsoft GW-BASIC number format. If underflow occurs, 
the result is zero and execution continues without an error. 


Out of memory 


A program is too large, or has too many FOR loops or 
GOSUBs, too many variables, or expressions that are too 
complicated for a file buffer to be allocated. 


Undefined line 


A nonexistent line is referenced in a GOTO, GOSUB, 
IF... THEN...ELSE, or DELETE statement. 


Subscript out of range 


An array element is referenced either with a subscript that is 
outside the dimensions of the array or with the wrong 
number of subscripts. 


Duplicate definition 


Two DIM statements are given for the same array; or, a 
DIM statement is given for an array after the default dimen- 
sion of 10 has been established for that array. 
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11 


12 


13 


14 


15 


16 


17 
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MESSAGE 


Division by zero 


A division by zero is encountered in an expression; or, the 
operation of involution results in zero being raised to a 
negative power. Machine infinity with the sign of the 
numerator is supplied as the result of the division, or positive 
machine infinity is supplied as the result of the involution, 
and execution continues. 

Illegal direct 


A statement that is illegal in direct mode is entered as a direct 
mode command. 


Type mismatch 


A string variable name is assigned a numeric value or vice 
versa; a function that expects a numeric argument is given a 
string argument or vice versa. 


Out of string space 


String variables have caused BASIC to exceed the amount 
of free memory remaining. Microsoft GW-BASIC will allo- 
cate string space dynamically, until it runs out of memory. 


String too long 


An attempt is made to create a string more than 255 charac- 
ters long.. 


String formula too complex 


A string expression is too long or too complex. The expres- 
sion should be broken into smaller expressions. 


Can’t continue 

An attempt is made to continue a program that: 
1. Has halted due to an error. 
2. Has been modified during a break in execution. 
3. Does not exist. 


Error Codes and Error Messages 


NUMBER 


18 


20 


21 


22 


23 


24 


2. 


26 


CH 


MESSAGE 


Undefined user function 


A USR function is called before the function definition 
(DEF statement) is given. 


No RESUME 


An error handling routine is entered but contains no 
RESUME statement. 


RESUME without error 


A RESUME statement is encountered before an error han- 
dling routine is entered. 


Unprintable error 


Anerror message is not available for the error condition that 
exists. 


Missing operand 

An expression contains an operator with no operand follow- 
ing it. 

Line buffer overflow 


An attempt has been made to input a line that has too many 
characters. 


Device timeout 


The device you have specified is not available at this time. 


Device fault 


An incorrect device designation has been entered. 


FOR without NEXT 


A FOR statement was encountered without a matching 
NEXT. 


Out of paper 
The printer device is out of paper. 
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28 


29 


30 


31-49 


Disk Errors 


NUMBER 


50 


51 


a2 


53 


Error Codes and Error Messages 


MESSAGE 


Unprintable error 


An error message is not available for the condition which 
exists. 


WHILE without WEND 
A WHILE statement does not have a matching WEND. 


WEND without WHILE 


A WEND statement was encountered without a matching 
WHILE. 


Unprintable error 


An error message is not available for the condition which 
exists. 


MESSAGE 


Field overflow 


A FIELD statement is attempting to allocate more bytes 
than were specified for the record length of a random file. 


Internal error 


An internal malfunction has occurred in Microsoft GW- 
BASIC. Report to Microsoft the conditions under which the 
message appeared. 


Bad file number 


A statement or command references a file with a file number 
that is not OPEN or is out of the range of file numbers 
specified at initialization. 


File not found 


A LOAD, KILL, NAME, or OPEN statement /command 
references a file that does not exist on the current disk. 


Error Codes and Error Messages 


NUMBER 


54 


fe 


56 


af 


58 


59-60 


61 


62 


63 


MESSAGE 


Bad file mode 


An attempt is made to use PUT, GET, or LOF with a 
sequential file, to LOAD a random file, or to execute an 
OPEN statement with a file mode other than I, O, or R. 


File already open 


A sequential output mode OPEN statement is issued for a 
file that is already open; or a KILL statement is given for a 
file that is open. 


Unprintable error 


An error message is not available for the condition that 
exists. 


Device I/O error 


An I/O error occurred on a disk I/O operation. It is a fatal 
error; 1.e., the operating system cannot recover from the 
error. 


File already exists 


The filename specified ina NAME statement is identical toa 
filename already in use on the disk. 


Unprintable error 


An error message is not available for the condition that 
exists. 


Disk full 


All disk storage space is in use. 


Input past end 


An INPUT statement is executed after all the data in the file 
has been INPUT, or for a null (empty) file. To avoid this 
error, use the EOF function to detect the end-of-file. 


Bad record number 


In a PUT or GET statement, the record number is either 
greater than the maximum allowed (32,767) or equal to zero. 


B-6 


“Ay, at 


NUMBER 


64 


65 


66 


67 


68 


69 


70 


71 


72 


Error Codes and Error Messages 


MESSAGE 


Bad file name 


An illegal form is used for the filename with a LOAD, 
SAVE, KILL, or OPEN statement (e.g., a filename with too 
many characters). 


Unprintable error 


An error message is not available for the condition that 
exists. | 


Direct statement in file 


A direct statement is encountered while LOADing an 
ASCII-format file. The LOAD is terminated. 


Too many files 


An attempt is made to create a new file (using SAVE or 
OPEN) when all 255 directory entries are full. 


Device Unavailable 


The device that has been specified is not available at this 
time. 


Communications buffer overflow 

Not enough space has been reserved for communications 
I/O. 

Disk write protected 


The disk has a write protect tab intact, or is a disk that 
cannot be written to. 


Disk not ready 


Could be caused by a number of problems. The most likely is 
that the disk is not inserted properly. 


Disk media error 


A hardware or disk problem occurred while the disk was 
being written to or read from. For example, the disk may be 
damaged or the disk drive may not be working properly. 
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NUMBER 


74 


75 


76 


> kK 


* 


MESSAGE 


Rename across disks 


An attempt was made to rename a file with a new drive 
designation. This is not allowed. 


Path/file access error 


During an OPEN, MKDIR, CHDIR, or RMDIR opera- 
tion, MS-DOS was unable to make a correct Path to File 
name connection. The operation is not completed. 


Path not Found 


During an OPEN, MKDIR, CHDIR, or RMDIR opera- 
tion, MS-DOS was unable to find the path specified. The 
Operation is not completed. 


You cannot run BASIC as a Child of BASIC 


No error number. During initialization, BASIC discovers 
that it is being run as a Child. BASIC is not run and control 
returns to the Parent copy of BASIC. 


Can’t continue after SHELL 


Noerror number. Upon returning from a Child process, the 
SHELL statement discovers that there is not enough 
memory for BASIC to continue. BASIC closes any open 
files and exits to MS-DOS. 
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== BARE > 


The following is a list of reserved words used in Microsoft GW-BASIC 2.0. 


ABS 
AND 


DATA 
DATE$ 
DEFDBL 
DEFINT 


-DEFSNG 


DEFSTR 
DEF FN 
DEF USR 
DELETE 


EOF 


MICROSOFT GW-BASIC Reserved Words 


LPRINT 
LSET 
MERGE 
MID$ 
MKD$ 
MKI$ 
MKS$ 
MKDIR 
MOD 
MOTOR 
NAME 


PALETTE 
PALETTE USING 
PEEK 

PEN 

PLAY 

PMAP 

POINT 

POKE 


POS 
PRESET 
PRINT 
PRINT# 


PRINT# USING 


PSET 
PUT 
RANDOMIZE 
READ 
REM 
RENUM 
RESET 
RESTORE 
RESUME 
RETURN 
RIGHTS$ 
RMDIR 
RND 
RSET 
RUN 
SAVE 
SCREEN 
SEG 

SGN 
SHELL 
SIN 
SOUND 
SPACE$ 
SPC 
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Not Intrinsic to GW-BASIC 2.0 


Derived Functions 


Functions that are not intrinsic to Microsoft GW-BASIC may be calcu- 


lated as follows. 
Function 


SECANT 
COSECANT 
COTANGENT 
INVERSE SINE 
INVERSE COSINE 
INVERSE SECANT 


INVERSE COSECANT 


INVERSE COTANGENT 
HYPERBOLIC SINE 
HYPERBOLIC COSINE 
HYPERBOLIC TANGENT 


HYPERBOLIC SECANT 
HYPERBOLIC COSECANT 
HYPERBOLIC COTANGENT 


INVERSE HYPERBOLIC 
SINE 

INVERSE HYPERBOLIC 
COSINE 


Microsoft GW-BASIC Equivalent 


SEC(X)=1/COS(X) 
CSC(X)=1/SIN(X) 
COT(X)=1/ TAN(X) 
ARCSIN(X)=ATN(X/SQR(-X*X+1)) 
ARCCOS(X)=-ATN(X/SQR(-X*X+1))+1.5708 
ARCSEC(X)=ATN(X/SQR(X*X-1)) 
+(SGN(X)-1)*1.5708 
ARCCSC(X)=ATN(X/SQR(X*X-1)) 
+(SGN(X)-1)*1.5708 
ARCCOT(X)=ATN(X)+1.5708 
SIN H(X)=(EX P(X)-EX P(-X))/2 
COS H(X)=(EX P(X)+EXP(-X))/2 
TAN H(X)=(EXP(X)-EX P(-X))/ 

(EX P(X)+EXP(-X)) 
SECH(X)=2/(EXP(X)+EX P(-X)) 
CSCH(X)=2/(EXP(X)-EX P(-X)) 
COT H(X)=(EXP(X)+EX P(-X))/ 

(EXP(X)-EXP(-X)) 


ARCSINH(X)=LOG(X+SQR(X* X+1)) 


ARCCOS H(X)=LOG(X+SQR(X*X-1)) 
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Mathematical Functions Not Intrinsic to GW-BASIC 2.0 


INVERSE HYPERBOLIC 
TANGENT 

INVERSE HYPERBOLIC 
SECANT 

INVERSE HYPERBOLIC 
COSECANT 

INVERSE HYPERBOLIC 

COTANGENT 


ARCTANH(X)=LOG((1+X)/(1-X))/2 
ARCSECH(X)=LOG((SQR(-X* X+1)+1/ X) 
ARCCSCH(X)=LOG((SGN(X)*SQR(X*X+1)+1)/X) 


ARCCOTH(X)=LOG((X+1)/(X-1))/2 


Appendix E 





Keyboard Diagram 
and Scan Codes 


The number to the under right designates the key position. 


SCAN CODES 
Table 1 Keyboard Scan Codes 
SCAN SCAN 
KEY CODE KEY CODE 
POSITION IN HEX POSITION IN HEX 

l 00 £2 15 

2 01 23 16 

3 02 24 17 

4 03 25 18 

5 04 26 19 

6 05 27 1A 

7 06 28 1B 

8 07 29 IC 

9 08 30 1D 
10 09 31] 74 
1] OA 32 71 
12 OB 33 1E 
13 0C 34 1F 
14 0C 35 20 
15 OE 36 21 
16 OF 37 Ze 
17 10 38 23 
18 1] 39 24 
19 IZ 40 25 
20 13 41 26 
21 14 42 27 
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Table 1 Keyboard Scan Codes (cont’d) 


SCAN 
KEY CODE KEY 
POSITION IN HEX POSITION 
43 28 72 
44 29 73 
45 70 74 
46 2A 75 
47 2B 76 
48 2C 77 
49 2D 78 
50 2E 79 
51 PAs 80 
52 30 81 
53 31 82 
54 32 83 
55 33 84 
56 vie: 85 
57 73 86 
58 34 87 
59 6E 88 
60 6F 89 
61 iD 90 
62 62 91 
63 63 92 
64 64 93 
65 65 94 
66 66 95 
67 67 96 
68 68 97 
69 69 98 
70 6A 99 
1 6B 100 


SCAN 
CODE 
IN HEX 


ye 


Appendix F 
The Differences 






Between APC II and Mere 
(GW-BASIC) 


1 THE PROGRAM EDITOR KEYS 


NO. 


1-] 


1-2 


1-3 


KEY(S) 


Break 


Ctrl+C 


Ctrl+Break 


APC Ill 


Exit AUTO line num- 
bering mode. 


Interrupts program ex- 
ecution at the Key- 
board input instruction 
and returns to BASIC 
command level. 


Interrupts program ex- 
ecution at the next 
BASIC instruction and 
returns to BASIC com- 
mand level. It also is 
used toexit AUTO line 
numbering mode. 


See NO. I-I 


F-] 


IBM PC 


See NO. 1-3 


Exit AUTO line num- 
bering mode. 


Interrupt program exe- 
cution at the Keyboard 
input instruction and 
returns to BASIC com- 
mand level. 


Interrupt program exe- 
cution at the next 
BASIC instruction and 
returns to BASIC com- 
mand level. It also is 
used toexit AUTO line 
numbering mode. 


Differences Between APCIII and IBM-PC (GW-BASIC) 


1-4 


1-5 


1-6 


GraphlI+ 
any key 

Graph2+ 
any key 


Ctrl+A 
Ctrl+Z 


Alt+M 


Used to enter graphics 
characters. 


Acts as special editor 
key. 


Associates “MID$”’. 


NOTE: The right side 
key of “SPACE KEY” 
is corresponding to 
“Alt” in APC III. 


2 THE FUNCTION KEYS 


2-1 


2-2 


Numbers of the 
function keys 


Initial value of 
the Function 
Keys 


Supports 12 Function 
Keys. 


Fl: LIST 
F2: AUTO 
F3 : RUN 
F4: LOAD” 
FS: SAVE” 
F6 : CONT 
F/:, LPT1:” 
F8 : TRON 
F9 : TROFF 
F10: KEY 
Fll: EDIT. 
F12: SCREEN 0,0,0 


F-2 


See NO. 1-5 


Used to enter graphics 
characters. 


Associates “MOTOR”. 


Supports 10 Function 
Keys. 


Fl: LIST 

F2: RUN 

F3 : LOAD” 

F4: SAVE” 

FS: CONT 

Fo? "LPT ic” 

F7: TRON 

F8 : TROFF 

F9: KEY 

F10 SCREEN 0,0,0 
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Differences Between APCIII and IBM-PC (GW-BASIC) 


Display of the 
Function Keys 


3 THE DEVICES 


NO. 


3-1] 


KEY(S) 


Device name 


6 (in case of the 
WIDTH 80) or 3 (in 
case of the WIDTH 
40) keys are displayed. 


In WIDTH 80 mode 
Display Fl~F6 
Press Ctrl+T key 
Display F7~F12 
Press Ctrl+T key 
Display off 


Press Ctrl+T key 


APC Ill 


KYBD: 

SCRN: 

COMI1: 

LPT I: 

CON: 

Disk 

NOTE: “CON” means 


“Standard Input/out- 
put Device.” 


10 (in case of the 
WIDTH 80) or 5 (in 
case of the WIDTH 
40) keys are displayed. 


IBM PC 


KYBD: 
SCRN: 
COMI: 
COM2?: 
COMs3: 
LPT: 
LPT2: 
LPT3: 
CASI: 
Disk 


Differences Between APCIII and IBM-PC (GW-BASIC) 


4 THE SCREEN 


4-] 


4-2 


Graphics 
Resolution 


Graphics page 


320 200 B/W 
320 200 

4 colors 
320 200 

8 colors 
640 200 B/W 
640 200 

4 colors 
640 200 

8 colors 
640 400 B/W 
640 400 

4 colors 


640 400 
8 colors 


F-4 


320 200 B/W 


320 200 
4 colors 


640 200 B/W 


Differences Between APCIII and IBM-PC (GW-BASIC) 


4-3. Foreground, Foreground: Foreground: 
Background 8 colors (color) 16 colors (color) 
and border 7 attributes (B/W) 3 attributes (B/ W) 
- colors ATTRIBUTES in ATTRIBUTES in 
| B/W mode B/W mode 
Color No. Color No. 
0 : blank 0 : blank 
1 : under line 1 : under line 
2 : blink 2 : white 
3 : over line 3 : white 
4 : reverse 4 : white 
5 : reverse 5 : white 
6 : reverse blink 6 : white 
7 : white 7 : white 


Background: NONE 
Border: 


NONE (In high 
resolution CRT) 


8 colors (In normal 
resolution CRT) 


Background:8 colors 
Border:16 colors 


5 COMMANDS, STATEMENTS AND FUNCTIONS 


NO. KEY(S) APC III IBM PC 


5-1 ENVIRON 
ENVIRON$ 
ERDEV 
ERDEV$ 

aa IOCTL 

~~ PALETTE 


PALETTE 
USING 


SHELL 
VIEW PRINT 


Supported Not supported 


Differences Between APCIII and IBM-PC (GW-BASIC) 


5-2 


5-3 


5-6 


5-7 


COLOR 
(In text mode) 


COLOR 
(In graphics 
mode) 


GET/PUT 
(In graphics 
mode) 


KEY n,X$ 
(user define) 


ON KEY(n) 


OPEN “COM: 


Foreground color : 
0~7 and 16~23 


Background color : 
NONE 


Border color : 
0~7 

Background color : 
0~7 


Palette mode : 
0~2 


Array stored image is 
byte repetition of Blue, 
Green and Red planes 
in color mode. 


Array size in color 
mode 


4+INT((x 3+7)/8) y 


n: 18~23 
x$: CHR$(scan code)+ 
CHRS&$(character code) 


n: I-~23 

NOTE 
Function key : 12 
Cursor move key : 4 
Help key: | 
User define key : 6 


Speed : 

Disable 110,1800 
Parity : 

Disable S,M 


Data bits : 
Disable 4 


BIN and ASC option: 


OK 
F-6 


Foreground color : 
0~31 

Background color : 

a 

Border color : 
0~15 

Background color : 
0~7 

Palette mode : 
0~|] 


Array stored image is 
bit repetition of 2 
colors element. 


Array size in color 
mode 


4+INT((x 2+7)/8) y \ 


wa) 
n: 15~20 
X$: CHR&§(shift code)+ 
CHR$(scan code) 


nt I~2O 

NOTE 
Function key : 10 
Cursor move key : 4 


User define key : 6 


Speed : 
Enable S,M | 
Parity : — 
Enable S,M 


Data bits : 
Enable 4 


BIN and ASC option: 
NONE 


a, 


* 


Please cut along this line. 





NEC 
APG bai NEC Information Systems, Inc. 


USER’S COMMENTS FORM 


Document: GW-BASIC USER’S GUIDE 


Document No.: 819-150032-000 Rev. 00 





Please suggest improvements to this manual. 


Please list any errors in this manual. Specify by page. 


From: 
Name 
Title 


Company 


Address 
Dealer Name 
Date: 





Seal or tape ali edges for mailing-do not use staples. 


FOLD HERE 


| | NO POSTAGE 
NECESSARY 
IF MAILED 
BUSINESS REPLY CARD 
FIRST CLASS PERMIT NO. 105 BOXBOROUGH, MA 


POSTAGE WILL BE PAID BY ADDRESSEE 


IN THE 
UNITED STATES 





NEC Information Systems, Inc. 
Dept: Publications 

1414 Mass. Ave. 

Boxborough, MA 01719 


— eur. a a ae ce ee cee cee cee cee oc ce oc oc oc oc ee oe ee ce ce oe ee ee 


FOLD HERE 
Seal or tape all edges for mailing-do not use staples. 


